Using the gaiia CLI

Last updated: November 11, 2026

Overview

The gaiia CLI is a command-line tool that lets developers and AI agents work with gaiia from the terminal. Install it on your computer and sign in once. You can run commands yourself, or let an AI agent such as Claude Code or Cursor run them for you.

Today, the CLI works with workflows: you or your agent can read your workflows, add and change steps, save drafts, and run tests. More areas of gaiia will be added over time.

Everything the CLI does, it does as you. It signs in with your gaiia user, so it can only see and change what your role allows, and every change shows up in gaiia like one you made yourself.

This article covers:

What you need before you install the CLI.
Installing it, signing in, and checking your setup.
The core commands, and keeping the CLI up to date.
Working with workflows: every workflow command, and the permission each one needs.
Fixing common problems.

Before you start

You'll need:

Node.js 22 or later, from nodejs.org.
npm, which comes with Node.js. See Downloading and installing Node.js and npm.
The Tools > Command-line tools permission in gaiia.

Downloading the CLI and signing in with it requires the Tools > Command-line tools permission. Ask your gaiia admin if you don't have it. Once you're signed in, every command runs, but the tool behind it checks your role, using the same permissions as the app. For example, reading workflows from the CLI requires the Workflows > View permission. See Working with workflows below.

Data the CLI returns is sent to your computer and to any AI tool you connect to it. See section 4.2 of the gaiia CLI Software License.

Installing the gaiia CLI

You download the CLI from gaiia, then install it with npm. It works on macOS, Linux, and Windows.

In gaiia, open Help & Support and find the CLI card.
Click How to install.
Click Download the CLI.
Read the gaiia CLI Software License, check the box to accept it on behalf of your organization, then click Accept and download.
Open a terminal in the folder your browser saved the file to, and run the install command shown on the How to install page.

To check the install, run gaiia --version.

Signing in and checking your setup

gaiia login --tenant <your-tenant-slug>
gaiia doctor

gaiia login opens gaiia in your browser so you can confirm the sign-in. gaiia doctor then checks everything at once: your CLI version, your sign-in, the connection to gaiia, and which tools you can use.

Signed in to more than one tenant? Add --tenant <slug> to each command, or run export GAIIA_AGENT_TENANT=<slug> once per terminal. When neither is set and you have several tenants, the CLI stops and lists them instead of guessing.

Core commands

These commands manage the CLI itself, whatever you use it for. Run gaiia --help for the current list, and add --help to any command to see its flags.

Command	What it does
`gaiia login --tenant <slug>`	Signs you in to a tenant through gaiia, so commands run as you.
`gaiia logout`	Signs you out of a tenant and removes its saved sign-in.
`gaiia tenants`	Lists the tenants you're signed in to.
`gaiia doctor`	Checks your version, sign-in, connection, and the tools you can use.
`gaiia upgrade`	Installs the latest version of the CLI. Add `--dry-run` to see what it would do first.
`gaiia --version`	Prints the installed version.

Keeping the CLI up to date

Run gaiia upgrade to install the latest version. gaiia doctor tells you when a newer one is out. You don't need to download anything from gaiia again.

Each release lists what changed in the CHANGELOG.md file that comes with the CLI. To find it, run npm root -g and open @gaiia-systems/cli in that folder.

Working with workflows

The workflow commands run as gaiia workflow <command>. They let you or your agent read, build, test, and publish workflows.

Working with an AI agent? Point it at the CLI. A good first prompt is "Run gaiia workflow help and gaiia workflow commands, then help me build a workflow." The CLI explains itself to the agent from there.

Sessions

You or your agent work on a workflow inside a session. A session holds changes between commands, until they're saved to a draft.

Start one session per workflow or draft with gaiia workflow session create. It prints the session ID.
Pass that ID with --session on every command for that workflow.
A session runs one command at a time. To work on several workflows at once, give each its own session.

For example, to start a session and show a workflow:

WELCOME=$(gaiia workflow session create)
gaiia workflow show --session "$WELCOME" --workflow-id <workflow-id>

From a change to a live workflow

Nothing edited through the CLI goes live until someone publishes it. A typical run looks like this:

Load a workflow or draft into a session with show.
Edit it with the step and trigger commands.
Check it with validate.
Save it to a draft with save-workflow.
Test the draft with start-workflow, then follow the run with executions.
Review the draft in the Workflow Builder.
Publish it with publish-workflow, or from the Workflow Builder.

Reading and discovery

These commands only read. They never change anything in gaiia. To use them, you need the Workflows > View permission.

Command	What it does
`session create`	Starts a new session and prints its ID.
`session status`	Describes the current session.
`help`, `commands`, `describe`	List every command and tool, or the flags of one.
`docs`	Browses the workflow documentation: steps, triggers, mappers, loops, and more.
`gaiia-docs`	Browses gaiia's data model: accounts, subscriptions, and how they connect.
`show`	Shows a workflow's structure: its trigger and steps. Works on any workflow, so you can copy patterns from one to another.
`show-step`	Shows the full definition of one step.
`versions`	Lists a workflow's published versions.
`executions`	Lists a workflow's runs, or shows the details and step outputs of one.
`workflow-schema`	Shows the input a workflow's trigger expects.
`nodes`	Lists the nodes available to build with, or the details of one.
`integrations`	Lists your integrations, or the details of one.
`events`	Lists the events a workflow can subscribe to, and what each one sends.
`custom-objects`	Lists your tenant's custom objects.
`types`	Shows the data types available at a step, for writing code and mappers.
`validate`	Checks a step's code, or the whole workflow, for type errors.
`api`	Searches the gaiia API and runs read-only queries against it.
`convert-id`	Converts between UUIDs and gaiia IDs.

Editing in a session

These commands change only the workflow inside your session. Nothing changes in gaiia until the session is saved to a draft.

Command	What it does
`set-trigger`	Sets the workflow's trigger: manual, webhook, event, or schedule.
`add-step`	Adds a step, wired in after an existing step or branch.
`update-step`	Changes some fields of a step.
`replace-step`	Replaces a step entirely, for example to switch its node.
`remove-step`	Removes a step, and warns about anything that still points to it.
`set-output-mapper`	Sets what the workflow returns when it ends.
`add-note`, `update-note`, `remove-note`	Add, change, or remove sticky notes on the canvas.

Tools that change data

These tools act on gaiia directly. Each one needs the workflow permission in the table. The CLI marks them, and prints a note before each run.

Tool	What it does	Workflow permission
`create-workflow`	Creates a new workflow.	`Workflows > Edit`
`update-workflow`	Changes a workflow's name, description, icon, or labels.	`Workflows > Edit`
`save-workflow`	Saves the session's changes to a draft.	`Workflows > Edit`
`delete-draft`	Deletes a draft and the test runs started from it. The live workflow doesn't change.	`Workflows > Edit`
`enable-workflow`, `disable-workflow`	Turns a workflow's trigger on or off. Only a published workflow can be enabled.	`Workflows > Edit`
`publish-workflow`	Publishes a draft as the live version.	`Workflows > Publish`
`start-workflow`	Starts a run of a workflow or draft and returns its ID without waiting.	`Workflows > Executions > Manage`

start-workflow runs the workflow for real. Every step runs, including ones that update accounts or send messages. Test on a draft with sample data before you run anything against live customers.

Two more tools never change anything: delete-workflow returns a link to delete the workflow yourself in gaiia, and waitForWorkflowExecution waits for a run to finish.

Troubleshooting

Installing and signing in

gaiia login says your tenant does not allow CLI sign-in

Your role doesn't have the Tools > Command-line tools permission. Ask your gaiia admin to add it to your role, then run gaiia login again.

npm can't find gaiia-systems-cli-latest.tgz

An older download was probably in the way, so your browser saved the new one under another name, usually with a number added. Delete the old files, download the CLI again, and rerun the install command.

gaiia upgrade can't sign in

Run gaiia login --tenant <slug> and try again. If it still fails, download the CLI again from Help & Support and reinstall it.

gaiia upgrade refuses to install on Windows

Your temporary folder's path contains a character Windows can't pass to npm, such as & or %. Set the TEMP environment variable to a folder without those characters, then run gaiia upgrade again.

Running commands

A command says "You do not have permission to use this tool."

The command ran, but your role doesn't have the permission the tool behind it needs. Ask your gaiia admin to add the permission for that module to your role, the same one you'd need to do it in the app. For example, reading workflows from the CLI requires the Workflows > View permission.

gaiia doctor says workflow-builder is missing

Your role doesn't give you any workflow tools yet. Ask your gaiia admin to add the workflow permissions you need, such as Workflows > View, then run gaiia doctor again.

A command fails with SESSION_ALREADY_PROCESSING

That session is still running another command. Wait for it to finish, or start a separate session for the parallel work.