Journey commands

This is the compact reference for the first developer journey. Run tanomis <command> --help for the complete flag set supported by your installed version.

Install

Terminal

curl -fsSL https://get.tanomis.com/install.sh | sh

One command on macOS and Linux; Windows uses irm https://get.tanomis.com/install.ps1 | iex. Pin with TANOMIS_VERSION; see Install tanomis.

Authenticate

Terminal

tanomis login --console https://api.tanomis.com --name saas
tanomis auth status
tanomis logout

login --console discovers the hosted configuration, creates or updates the named context, and starts device authorization by default. logout clears cached credentials but keeps the context. Follow Authenticate and select a workspace for the complete human login, context, workspace-discovery, selection, and failure flow.

Discover and scaffold

Terminal

tanomis agent harnesses

tanomis agent new NAME \
  --harness claude-agents-sdk \
  --agents-root ./agents \
  --description "What this agent does"

--harness accepts a value reported by agent harnesses. --agents-root can point anywhere, including an external repository. Scaffolding writes a self-contained project and runs uv lock when uv is available.

Validate and deploy

Terminal

tanomis agent deploy PATH --tenant TENANT --dry-run
tanomis agent deploy PATH --tenant TENANT
tanomis agent deploy PATH --scope global --tenants all

--tenant deploys to one tenant. --scope global --tenants all registers a global agent once and enables it for every active tenant; a platform operator’s path.

Useful deploy flags:

Flag	Meaning
--dry-run	Preflight and package locally; create no build and upload nothing.
--version VERSION	Override the version from agent.yaml.
--no-wait	Return after upload instead of waiting for terminal build status.
--no-stream-logs	Poll status without streaming build events.
--output json	Emit machine-readable output for automation.

The supported remote build profile is python-managed. Remote builds require uv.lock or a requirements.txt; pin every requirement to keep builds reproducible. The CLI verifies that the file exists but does not inspect its entries. --allow-unlocked is not supported.

Inspect

Terminal

tanomis agent ls --tenant TENANT
tanomis agent get NAME --tenant TENANT
tanomis agent versions NAME --tenant TENANT
tanomis agent versions NAME --by-tenant

Use get for an agent-centric view and versions --by-tenant for the reverse rollout view.

Roll out and roll back

Terminal

tanomis agent rollout NAME --version VERSION --tenants TENANT --dry-run
tanomis agent rollout NAME --version VERSION --tenants TENANT --canary-share 10
tanomis agent versions NAME --by-tenant

rollout promotes the requested global version if needed, then assigns it only to the requested tenants. Omit --canary-share for a baseline assignment; a value from 1 through 99 uses each tenant’s baseline observed at command start and adds the version as a canary. Serialize assignment changes for each tenant so a cached baseline cannot overwrite a concurrent rollout. Treat output as provisional: a tenant assignment failure can appear as success. Only a follow-up versions --by-tenant read verifies the assignment. Roll back with named-tenant agent enable --baseline KNOWN_GOOD; built-in deprecated versions remain serveable even though rollout cannot transition them back to production. Require zero failed in the enable summary and verify the version view. Comma-separated tenant batches require ordinary authority over every target; support act-as assertions are tenant-bound, so run one tenant per command under its own assertion. agent disable removes enablement and stops service; it does not select an older version.

Follow the rollout and rollback tutorial before changing customer tenant assignments.

Run

Terminal

tanomis session run NAME \
  --tenant TENANT \
  --prompt "Your prompt"

session run creates a session, starts a run, and streams events through the managed runtime. Use --input '{"key":"value"}' for raw JSON instead of --prompt; the two flags are mutually exclusive. Use --no-stream to print the run ID without following events.

Automate

Terminal

tanomis m2m create ci-deployer --profile deploy
tanomis m2m ls
tanomis m2m rotate ci-deployer

m2m create prints the client ID and secret once. Set TANOMIS_API_URL, TANOMIS_CLIENT_ID, and TANOMIS_CLIENT_SECRET in a job and every command above runs unattended; see Automation credentials.

Command-scoped context

The active context applies automatically. Select another existing context for one command without switching:

Terminal

tanomis agent ls --context staging --tenant TENANT

--context selects an existing context. login --name names the context created by login --console.