CLI reference

The tau command connects your terminal to a Tau instance. Use it to inspect squads, create and follow work streams, and script supported actions. The examples below assume tau is installed and available on your PATH; check with tau --version.

Log in to an instance

Choose a short label for the connection, such as work. Tau calls a saved connection a backend.

Tau CloudSwitch to Self-hosted

Use the URL of your own Tau workspace. Replace the fictional https://tau.example.com address before running:

tau auth login work --api-url https://tau.example.com

Self-hostedSwitch to Tau Cloud

Use your instance’s browser-facing base URL. If you are running the CLI on the same machine as a local instance on port 3000:

tau auth login local --api-url http://localhost:3000

For a remote server, replace the URL with that server’s address. See Runtime and access if the instance is not reachable.

Without an explicitly supplied credential, login opens browser approval or prints a URL to open. Sign in to the intended account and approve the CLI. The command saves the paired credential and makes this backend active.

Check the target and identity before creating work:

tau auth status
tau whoami
tau auth introspect

auth status explains how the CLI found its credentials. whoami identifies the instance and caller; auth introspect shows effective roles and permissions. Explicit environment credentials can affect authentication, so check these when the CLI appears to use the wrong account.

Find a squad and workflow

tau squad list
tau workflow list
tau agent-type list

Copy an actual squad ID from the list. This example value is fictional and must be replaced:

SQUAD_ID='00000000-0000-4000-8000-000000000001'
tau squad get "$SQUAD_ID"
tau workstream list --squad "$SQUAD_ID"

If you need a squad, this creates one with a name and purpose:

tau squad create "Website refresh" --purpose "Improve the public website"

Read Squads to choose its workspace and configuration before assigning work.

Create and inspect a work stream

Choose a workflow from tau workflow list. This example uses the bundled solo style, which gives one participant the deliverable:

tau workstream create "Draft release notes" \
  --squad "$SQUAD_ID" \
  --workflow solo \
  --description "Draft release notes from the changes provided in the squad. Identify anything that needs verification."

Participants are created when their flow steps are reached. You do not need to pre-spawn agents for this style-based path. See Workflows for choosing a flow and completion behavior.

Copy the returned work-stream ID. Replace this fictional value before running:

WORKSTREAM_ID='00000000-0000-4000-8000-000000000002'
tau workstream get "$WORKSTREAM_ID"
tau workstream get "$WORKSTREAM_ID" --metrics
tau workstream list --squad "$SQUAD_ID" --no-truncate

ws is an alias for workstream; at is an alias for agent-type. To find work by text:

tau search "release notes" --squad "$SQUAD_ID" --limit 10

Use multiple instances

List saved backends, switch the default, or select one for a single command:

tau auth list
tau auth switch work
tau --backend work squad list

Replace work with a label you have saved. Backend selection is for a person’s CLI session. Tau-built agent shells use their injected agent identity and reject --backend so they do not accidentally pick up an operator login.

Use JSON in scripts

Add --json for machine-readable output:

tau --json squad list
tau --json workstream get "$WORKSTREAM_ID"
tau --json auth introspect --squad "$SQUAD_ID"

Inspect the command’s returned fields before writing a script around them. A successfully retrieved work-stream record is not evidence that its work is complete; check its status and any outstanding input or review request.

For automation, use a separately scoped system token. Supply TAU_API_URL and TAU_TOKEN through your automation’s secret/environment configuration rather than placing a token in a command or checked-in script.

Discover commands and troubleshoot

Inspect disk usage

Read the same cached breakdown shown in Settings → Storage, or request a background scan:

tau system storage --json
tau system storage --refresh --json

Both commands return immediately with scanning, scannedAt, error, and the per-machine, squad, and folder sizes in bytes. While scanning is true, read again after a few seconds; existing results retain the previous scan’s timestamp until the scan finishes. Check each machine’s status: unavailable or partial measurements are not evidence of an empty disk. Folder totals include their children.

Squads and folders also have a status. On an interrupted scan, completed child measurements are retained under partial parents without counting overlapping subtrees twice. A bytes: null value means nothing was measured, rather than zero usage. Folder path identifies the measured directory. Machine diagnostics includes the command’s exitCode, reason codes such as scan_timeout or permission_denied, and expectedHomes, measuredHomes, and missingHomes. Missing home totals alone do not establish whether a directory is absent, unreadable, or simply not reached before the time limit.

Storage scans also run on the worker every 12 hours by default. Configure the interval and capacity alerts in Settings → Storage. Reading storage does not itself trigger a scan; a manual refresh queues one for the next worker check. --refresh has a one-minute cooldown; concurrent requests share the running scan. This requires system:logs permission and VM sandbox machines. Other runtimes return supported: false. The User Assistant can use these commands with your permissions.

The API equivalents are GET /api/system/storage and POST /api/system/storage/refresh, with the same permissions and persisted results. See disk troubleshooting for measurement limits.

Get help

tau --help
tau workstream create --help
tau agent-type update --help
tau integration --help
tau provider-auth --help

Symptom	What to check
Wrong instance or account	Run tau auth status and tau whoami; inspect explicit environment overrides and the active backend.
Unauthorized	Log in again or check whether the paired device was revoked.
Forbidden	Run tau auth introspect --squad "$SQUAD_ID" and ask an administrator for the required access.
No usable model	Check provider accounts and the selected model tier.
Unknown option	Read that command’s --help; CLI and server versions may differ.

To disconnect a saved backend:

tau auth logout work

Normal logout revokes its paired device and removes the local credential. If the server is unreachable, tau auth logout work --local-only removes the local entry without revoking the remote device; revoke it later in Settings → Paired Devices.

For a guided first run, follow Your first task.

Work references

Use the short number shown in Tau for work-stream commands:

tau workstream get 42
tau workstream get '#42'

Full UUIDs and unique UUID prefixes remain accepted. --json responses retain the UUID id and include number; --id-only prints the public number. In API paths, use /api/workstreams/42 or encode the hash: /api/workstreams/%2342.