Griptape Cloud CLI

The Griptape CLI is a command-line interface for interacting with features of Griptape Cloud. Today, it provides an emulator for Griptape Cloud Managed Structures, which allows you to run and test your Managed Structures locally.

Prerequisites

• A GitHub account.
• Python 3.11.
• Poetry for running the example client program.
• Linux operating system functionality. For Windows users, Griptape recommends the Windows Subsystem for Linux (WSL) for this functionality.

Installation

1. Install griptape-cli

   pipx install griptape-cli

   You can also install a pre-release version from GitHub.

   git clone https://github.com/griptape-ai/griptape-cli.git

   pipx install ./griptape-cli --force

2. Verify installation

   gt --help

Skatepark Emulator

You can use the CLI to spin up Skatepark, a local emulator for Griptape Cloud Managed Structures. It exposes an API that is identical to the one you would interact with when running your Managed Structure in Griptape Cloud. Use Skatepark to develop, test, and validate that your program will operate as expected when deployed as a Griptape Cloud Managed Structure. Skatepark gives you confidence that when you bring your Structure into Griptape Cloud as a Managed Structure, it will continue to operate as expected, at scale.

1. Start by creating a new repository in your own Github account from the Managed Structure Template.

   1. Make sure you're logged in to GitHub.
   2. Go to the Managed Structure Template repo.
   3. Select the Use this template drop-down.
   4. Choose Create a new repository.
   5. Provide a name for the new repository and (optionally) a description.
   6. Press the Create repository button.
   7. You now have a repository in your own GitHub account that is a copy of the Managed Structure Template for you to begin working with.

2. Clone your newly-created repository to a directory in your local development environment so that you can begin authoring your own Griptape Cloud Managed Structure.

3. Start Skatepark.

   gt skatepark start

4. Open a new terminal window. Navigate to the directory with the locally-cloned repository.

5. Register a Structure with Skatepark.

   gt skatepark register --structure-config-file structure_config.yaml

   This will result in the ID of the registered Structure. It is important to make note of this ID as it will be used to distinguish which Structure you want to run. You can register any number of Structures.

   The example client program uses the environment variable GT_STRUCTURE_ID to determine which Structure to run. Set this environment variable to the Structure ID you registered in the previous step.

   export GT_STRUCTURE_ID={STRUCTURE_ID}

   Or you can register and set the environment variable in one step.

   export GT_STRUCTURE_ID=$(gt skatepark register --structure-config-file structure_config.yaml --tldr)

   [!IMPORTANT] Structures registered with the Skatepark are not persisted across restarts. You will need to re-register the Structure each time you restart Skatepark.

6. Confirm that the Structure is registered.

   gt skatepark list

   You should see a list of registered Structures and the directories they point to, confirming that your Structure was properly registered

7. You can load environment variables into your Structure by creating an .env file in the directory of the Structure you registered.

   1. Create a file named .env in the same directory that your Structure code is in.
   2. Open the .env file in a text editor.
   3. Copy the contents of .env.structure.example into the .env file. This specifies all of the values necessary and explains how they are used.
   4. The template expects an OPENAI_API_KEY environment variable by default to function. Add OPENAIAPI_KEY=_your OpenAI API Key here to the .env file and save it.
   5. As you expand on the template, you may add any other environment variables your Structure depends on to this file.

8. Rebuild the structure to load in the new environment variable. Note that this is only required for changes to .env or requirements.txt. Code changes do not require a rebuild.

   gt skatepark build

9. Now that your Structure is registered and built, we want to be able to call it from within another program. The managed structure template offers an example client that can invoke your Structure. You have to configure the client with details on where to find the Structure in order for it to be called.

   1. Create a file named .env in the example-client directory.
   2. Open the .env file in a text editor
   3. Copy the contents of .env.client.example (located within the example-client/ directory) into the .env file. This specifies all of the values necessary and explains how they are used.
   4. The client needs to know where the Structure is hosted, as specified in the GT_CLOUD_BASE_URL environment variable. When testing against the Skatepark emulator, we will use the default value address that Skatepark is running on. Set GT_CLOUD_BASE_URL=http://127.0.0.1:5000.
   5. The client needs to know which Structure it is attempting to invoke, as specified in the GT_STRUCTURE_ID environment variable. This is the same value you got when you registered the Structure with Skatepark in step 5. You can quickly get this value by typing gt skatepark list to see the list of all registered Structures. Copy this value into GTSTRUCTURE_ID=_your Skatepark Structure ID here.
   6. Save the .env file.

10. The example client is configured, now you can use it to call Skatepark's API for running the Structure.

    Navigate to the example-client directory.

    cd example-client

    Install the dependencies required by the example client program.

    poetry install --no-root

    Run the example client program.

    poetry run python client.py

    You should see the result of the Structure answering What is 123 * 34, 23 / 12.3, and 9 ^ 4, indicating a successful run.

Important

The client program is an example for how to interact with the Managed Structure's API. It is useful for testing your Managed Structure locally, but ultimately you will want to integrate your Managed Structure with your own application.

Simulating Structure Run Delay

By default, Skatepark adds a 2 second delay before transitioniong Structure Runs from the QUEUED state to the RUNNING state. If you want to change this delay in order to test the behavior of your Structure when it is in the QUEUED state, you can do so by setting the GT_SKATEPARK_QUEUE_DELAY environment variable. For example, a value of GT_SKATEPARK_QUEUE_DELAY=5 will cause Skatepark to wait 5 seconds before transitioning the Structure Run from QUEUED to RUNNING. Setting a value of GT_SKATEPARK_QUEUE_DELAY=0 will cause Skatepark to transition the Structure Run immediately.

Note that this environment variable must be set in the terminal where the Skatepark server is running, not in the terminal where the client program is run.

Documentation

Please refer to Griptape Docs

Development

poetry install
poetry run gt

Tests

poetry run pytest

Contributing

Thank you for considering contributing to Griptape! Before you start, please read the following guidelines.

Submitting Issues

If you have identified a bug, want to propose a new feature, or have a question, please submit an issue through our public issue tracker. Before submitting a new issue, please check the existing issues to ensure it hasn't been reported or discussed before.

Versioning

Griptape CLI is in constant development and its APIs and documentation are subject to change. Until we stabilize the API and release version 1.0.0, we will use minor versions (i.e., x.Y.z) to introduce features and breaking features, and patch versions (i.e., x.y.Z) for bug fixes.

License

Griptape CLI is available under the Apache 2.0 License.