# Journey commands

A focused reference for the tanomis commands used to authenticate, scaffold, deploy, inspect, and run.

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

```bash
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](/getting-started/install).

## Authenticate

```bash
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](/getting-started/authenticate-and-select-workspace)
for the complete human login, context, workspace-discovery, selection, and failure flow.

## Discover and scaffold

```bash
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

```bash
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

```bash
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

```bash
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](/guides/deploy/rollout-and-rollback) before changing customer
tenant assignments.

## Run

```bash
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

```bash
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](/guides/deploy/automation-credentials).

## Command-scoped context

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

```bash
tanomis agent ls --context staging --tenant TENANT
```

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