The Compass CLI

The compass command-line tool is a full management surface for the platform — not just running and inspecting work, but authoring it. From a terminal you can create agents (interactively or from flags), build, validate, and deploy workflows, manage connections, and inspect runs — every command scriptable for automation and CI. It's distributed as a Python wheel you download from the app.

Install

Download the wheel from Settings → Developers → SDK / CLI (the Download wheel button), then install it as a tool:

uv tool install "./compass_cli.whl[cli]"

This puts a compass command on your PATH. It needs Python 3.13+; the [cli] extra pulls in the terminal dependencies. (pipx install "./compass_cli.whl[cli]" works too.)

Log in

Authenticate once with an API key:

compass auth login --url https://your-compass-url

You'll be prompted for the key, which is saved to a local profile. Check it worked with compass auth whoami, and sign out with compass auth logout.

Profiles and environment

Credentials are stored in a config file under ~/.config/compass/, and you can keep several profiles (for example, different organizations or environments):

compass config list          # show saved profiles
compass config use <name>    # switch the default profile
compass --profile <name> ... # use a profile for one command

Any command also reads these environment variables, which override the saved profile:

Variable	Purpose
`COMPASS_API_KEY`	The API key to authenticate with.
`COMPASS_BASE_URL`	Your Compass URL.
`COMPASS_PROFILE`	Which profile to use.

Output formats

Most commands print a readable table by default. Use -o (--output) to get machine-readable output for scripting:

compass workflows list -o json
compass runs get <run-id> -o yaml

Commands

Group	What it does
`compass auth`	`login`, `logout`, `whoami`.
`compass config`	Manage profiles (`list`, `use`, `path`).
`compass workflows`	`list`, `get`, `create`, `update`, `delete`, `validate`, `deploy`.
`compass agents`	`list`, `get`, `create`, `run`, `delete`.
`compass run`	Start a run of a deployment or workflow.
`compass runs`	Inspect runs: `list`, `get`, `executions`, `tree`.
`compass conversations`	`list`, `get`, `delete`.
`compass connections` · `providers` · `gateways`	Manage each kind of connection.

Run compass --help, or compass <group> --help, to see every option.

Create an agent

compass agents create builds an agent without opening the app. Run it with no arguments for an interactive wizard that walks you through the name, instructions, provider and model, and tools:

compass agents create

Or pass everything as flags — ideal for scripts and repeatable setups:

compass agents create \
  --name "Release Notes Writer" \
  --instructions "You write concise release notes from a list of changes." \
  --provider <provider-connection-id> \
  --model claude-sonnet-4-6 \
  --tool integration:<connection-id> \
  --tool workflow:<workflow-id> \
  --no-conversation-history

The --tool flag is repeatable and accepts agent:<id>, workflow:<id>, or integration:<connection-id> — the same three tool kinds as the builder. You can also create from a saved JSON definition with --file agent.json.

Build and deploy workflows

Create a workflow from a definition file, validate it, and deploy it — the whole lifecycle from the terminal:

compass workflows create --file workflow.json
compass workflows validate <workflow-id>
compass workflows deploy <workflow-id>

Because agents are workflows under the hood, the workflow validate, deploy, and versions commands work on an agent's id too — so you can deploy an agent you created above with compass workflows deploy <agent-id>.

Manage connections

The connections, providers, and gateways groups create and manage connections from the terminal (creating connections needs an admin key):

compass providers list
compass connections create

Run and inspect

# Run a deployment and follow it live
compass run --deployment <deployment-id> --input topic="Q3 report" --follow

# Run a workflow draft from a JSON input file
compass run --workflow <workflow-id> --input @inputs.json

# Chat with an agent
compass agents run <agent-id> --message "Summarize today's signups" --follow

# Inspect a run afterward
compass runs get <run-id>
compass runs tree <run-id>

--follow streams live

Adding --follow (-f) to a run streams events as they happen — tool calls, output, and completion — the same trace you'd see in Observability.

Scriptable end to end

Combine these with -o json to drive Compass from CI or scripts — create an agent, deploy it, kick off a run, and parse the result, all without the UI.

The Compass SDK

The same capabilities from Python code.

Running via the API

The HTTP endpoints underneath.