CLI

To install the stately CLI, follow the Getting Started guide. You can upgrade the CLI to the latest version with stately upgrade.

The CLI has built-in help (run stately help), but notable commands are also explained here.

Authentication

stately login allows you to log in to your Stately account. Once you log in, subsequent commands will use this account until you run stately logout. Note that there is currently no way to run the CLI using the Client ID and Client Secret of a Service Account.

whoami

stately whoami prints information about the currently logged in user and all of the resources they have available to them. This is a quick way to get ahold of Store IDs or Schema IDs, which are useful in other commands such as updating schema.

schema

The stately schema subcommands allow you to create and update schema versions, as well as generating language-specific client code.

create / bind

stately schema create adds a new Schema to your Organization, and returns its Schema ID. Generally you won’t have to do this, as Stately Support will create a Schema for you with your first Store. You can then call stately schema bind to bind the Schema to one of your Store.

stately schema create \
--project-id <your project ID> \
--name "Schema Name" \
--description "A description"
stately schema bind --schema-id <your schema ID> --store-id <your store ID>

init

stately schema init sets up a NodeJS package containing your schema definition TypeScript files. The only argument is the directory path you want to create. The directory must not exist already.

stately schema init ./schema

generate

stately schema generate will run your schema TypeScript files and then create code in one of our supported SDK languages that contains typed objects corresponding to the types in your schema. For this to run, you need to have NodeJS installed, and have installed the dependencies for your schema package with npm install.

The first positional argument is the path to your schema’s index file (you can have schema in as many TypeScript files as you want as long as there’s a single file that exports everything). The second positional argument is the output directory where the language-specific code will go.

stately schema generate --language go ./schema/schema.ts lib

put

stately schema put publishes a new version of your schema. This will also run your schema TypeScript files. For this to run, you need to have NodeJS installed, and have installed the dependencies for your schema package with npm install.

The first positional argument is the path to your schema’s index file (you can have schema in as many TypeScript files as you want as long as there’s a single file that exports everything).

stately schema put --schema-id <your schema ID> path/to/schema.ts

stately schema put will fail if you are making a backwards-incompatible change to your schema. You can add the --force argument to override this, but realize you’re taking the validity of your stored data into your own hands at that point. Eventually we will remove the --force option when Elastic Schema can handle all types of changes—in the meantime, it is sometimes necessary to override the backwards compatibility check when you know it’s safe.

print / validate

stately schema print and stately schema validate are very similar. Both run your schema TypeScript files. For this to run, you need to have NodeJS installed, and have installed the dependencies for your schema package with npm install.

validate will check to make sure your schema is valid. It will exit with a nonzero exit code if the schema is invalid. This command does not require that you specify a store and it does not check for backwards compatibility with an existing schema.

print is exactly the same as validate, except it prints the resolved schema out in a sort of concise, readable format.

item

The stately item subcommands allow for updating or fetching items from the CLI. We strongly recommend using our SDKs instead, since they let you work with typed objects instead of JSON, but sometimes you just have to write a script.

The operations mirror the StatelyDB APIs: get, put, delete, and list. The API reference has examples of using the CLI to perform each of these.