# CLI

The taskstation command line, its auth model, the dev loop, and every command.

Canonical page: https://taskstation.co/docs/cli

The `taskstation` command line interface (CLI) controls TaskStation from a terminal — your laptop or a session sandbox. This page shows the everyday dev loop, then lists every stable command and flag.

## Install

```sh
curl -fsSL https://taskstation.co/install | bash
```

The installer downloads a prebuilt binary for macOS and Linux. Windows is not supported.

| Command | Effect |
| --- | --- |
| `taskstation update` | Re-run the install script and pull the latest binary. |
| `taskstation uninstall [-y\|--yes] [--keep-auth] [--keep-home]` | Remove the binary, the `/usr/local/bin` shim, and the stored token. `--keep-auth` keeps the token. `--keep-home` keeps `~/.taskstation`. |
| `taskstation version` | Print the CLI version. |

## Auth model

TaskStation stores authentication per host, not globally. A host is one TaskStation API endpoint. Four hosts exist by default: `cloud` (TaskStation Cloud), `selfhost` (your self-hosted stack), `local-dev`, and `taskstation-internal-dev`. You can add more.

The config file lives at `~/.config/taskstation/config.json`, mode `0600`. Override its path with `TASKSTATION_CONFIG_FILE`.

The CLI follows one hierarchy: host → account → project → session. You sign in to a host, pick an account inside it, pick a project inside that account, and open sessions inside the project. `taskstation hosts login` walks the first three steps in order: it signs you in, picks the account, then sets a default project.

Every token starts with `taskstation_pat_`. A user token, from `taskstation login`, sees every account and project you belong to. A project token is auto-minted for a session sandbox and scoped to one project. See [Token scope](#token-scope).

## The dev loop

This loop assumes the CLI is installed and you ran `taskstation login`. See [Quickstart](/docs/quickstart) for setup.

### Link a repo

Start a new project, or link an existing repo folder to one.

To scaffold a new project:

```sh
taskstation init my-app
cd my-app
```

`taskstation init` creates a project directory with the general-purpose starter. Its
`taskstation.yaml` declares `taskstation_version: 2` and runs OpenCode.

To link an existing cloned repo to a project you already created:

```sh
taskstation projects link <project-id>
```

This command writes `.taskstation/link.json` in the current directory. TaskStation reads this file to find your project on every command run from this folder. If you plan to run `taskstation ship` first, skip this step. It links a new project for you when none exists.

### Ship your code

```sh
taskstation ship
```

`taskstation ship` lints your `taskstation.yaml`, commits local changes, pushes your branch, and prompts for any missing secret or connection. Run it each time you want your local changes on the cloud project. The first run also creates the cloud project and repo if you have not linked one yet.

### Run and attach to sessions

Start a session with a prompt:

```sh
taskstation sessions new --prompt "Build the login page" --wait
```

Each session runs in its own sandbox, on its own branch. `--wait` blocks until the session is ready.

Attach to a session from your terminal:

```sh
taskstation connect
```

With no session id, `taskstation connect` (alias: `attach`) opens a session picker
for the bound project — running sessions attach immediately, stopped ones boot
first, and `+ New session` starts a fresh sandbox — then lands you in the full
OpenCode TUI attached to that session. Pass an id to skip the picker:
`taskstation connect <session-id>`.

The CLI manages the `opencode` binary for you: on first connect it downloads
the exact version the session's server runs and caches it under
`~/.taskstation/opencode/<version>/`, so the TUI and server never skew. Set
`TASKSTATION_OPENCODE_BIN` to force your own binary.

For a lighter-weight line-based chat instead of the full TUI, run:

```sh
taskstation sessions chat
```

This opens an interactive chat with your most recent session. Add an id to target a specific session: `taskstation sessions chat <id>`.

To open a raw shell in the sandbox, with no agent involved, run:

```sh
taskstation sessions shell
```

List your running sessions at any time:

```sh
taskstation sessions ls
```

### Review with change requests

An agent opens a change request (CR) when its session has commits ready to merge. List, inspect, and merge them from the CLI.

```sh
taskstation cr ls
taskstation cr diff 1
taskstation cr merge 1
```

`taskstation cr ls` lists change requests for the linked project. `taskstation cr diff <cr>` shows the unified patch. `taskstation cr merge <cr>` merges it into the project's default branch. Accept a CR number or its full id.

## Reference

### Auth commands

| Command | Effect |
| --- | --- |
| `taskstation login [--host <name>] [--api <url>] [--token <pat>] [--account <slug>] [--no-project]` | Sign in to the active host, or the named one. Opens a browser by default; `--token` signs in headless. `--no-project` skips the default-project pick. |
| `taskstation logout [--host <name>]` | Remove the token for the active host, or the named one. |
| `taskstation whoami [--host <name>] [--json] [--token-only]` | Print the signed-in user and active account. |
| `taskstation token [--host <name>]` | Shortcut for `taskstation whoami --token-only`. |

`taskstation hosts login` / `hosts logout` / `hosts whoami` are the canonical forms. `login` / `logout` / `whoami` are shortcuts that act on the active host.

### Hosts

| Command | Effect |
| --- | --- |
| `taskstation hosts ls [--json]` | List every host and its auth status. |
| `taskstation hosts login [<name>] [--token <pat>] [--api <url>] [--account <slug>] [--no-project]` | Sign in to a host. An unknown name registers the host first. |
| `taskstation hosts logout [<name>]` | Remove the token for a host. |
| `taskstation hosts use <name>` | Switch the active host. |
| `taskstation hosts add <name> --url <url> [--dashboard-url <url>] [--login]` | Register a new host. `--login` signs in right after. |
| `taskstation hosts rm <name> [--force]` | Remove a host. |
| `taskstation hosts info [<name>] [--json]` | Show details for one host. |
| `taskstation hosts current [--json]` | Print the active host name. |

A remote host URL that starts with `http://` is normalized to `https://`. The CLI never sends a token over plain HTTP to a remote host. `localhost` is exempt.

### Accounts

| Command | Effect |
| --- | --- |
| `taskstation accounts ls [--json]` | List the accounts you belong to on the active host. |
| `taskstation accounts use [<slug-or-id>]` | Switch the active account. |
| `taskstation accounts current [--json]` | Print the active account. |
| `taskstation accounts info [<slug-or-id>] [--json]` | Show one account. |

### Members

Who belongs to the account, and at what account role. Roles are `owner`,
`admin`, and `member`. Owners and admins hold implicit Manager on every
project, so `member` is the only role that takes per-project grants.

| Command | Effect |
| --- | --- |
| `taskstation members ls [--json]` | List members, roles, and project counts. |
| `taskstation members invite <email> --role admin\|member [--project <id>:<role>]` | Invite by email. An existing TaskStation user is added immediately; anyone else is mailed an invite link. `--project` is repeatable and applies on accept. Needs `member.invite`. |
| `taskstation members set-role <user\|email> --role owner\|admin\|member` | Change an account role. Needs `member.update`; the `owner` role is owner-only. |
| `taskstation members rm <user\|email> [-y\|--yes]` | Remove a member and revoke their tokens. Needs `member.remove`. |
| `taskstation members super-admin <user\|email> on\|off` | Grant or revoke the super-admin bypass. Needs `member.super_admin.grant`. |
| `taskstation members invites ls [--json]` | List pending invitations you sent. |
| `taskstation members invites cancel <invite-id>` | Cancel one pending invitation. |
| `taskstation members invites resend <invite-id>` | Re-send the email and refresh the 14-day expiry. |

A `<user>` is a user id, or the email of someone already in the account.
Options: `--account <id>`, `--host <name>`, `--json`, `-y`.

### Groups

An account group is a named set of people you grant a role to once. Bind a
group to a scope with `taskstation access grant --group <id> --role <key>`; revoke
with `taskstation access revoke <assignment-id>`.

| Command | Effect |
| --- | --- |
| `taskstation groups ls [--json]` | List groups with member and project counts. |
| `taskstation groups create <name> [--description <t>]` | Create a group. |
| `taskstation groups set <group> [--name <n>] [--description <t>\|--no-description]` | Rename or re-describe a group. |
| `taskstation groups rm <group> [-y\|--yes]` | Delete a group. Its grants go with it. |
| `taskstation groups members <group> [--json]` | List a group's members. |
| `taskstation groups add <group> <user>...` | Add one or more people. |
| `taskstation groups remove <group> <user>` | Remove one person. |
| `taskstation groups projects <group> [--json]` | Which projects the group reaches, and at what role. |

A `<group>` is a group id or its exact name. Reads need `group.read`.
`create`, `set`, and `add` need `group.update` or `group.members.manage`, plus
the enterprise `rbac` entitlement. `rm` and `remove` are cleanup and are never
entitlement-gated.

### Tokens

Non-interactive credentials for the account. Reads need `token.read`, minting
needs `token.create`, revoking needs `token.revoke`.

| Command | Effect |
| --- | --- |
| `taskstation tokens ls [--mine] [--json]` | List the account's personal API keys. `--mine` narrows to the ones you minted. |
| `taskstation tokens new <name> [--expires <when>] [--project <id>]` | Mint a key. The secret prints once. `--project` binds it to one project, which it can never leave. |
| `taskstation tokens rm <token-id> [-y\|--yes]` | Revoke a key immediately. |
| `taskstation tokens service-accounts ls [--json]` | List service accounts. |
| `taskstation tokens service-accounts new <name> [--description <t>] [--expires <when>]` | Create one. The bearer prints once. |
| `taskstation tokens service-accounts disable <id>` | Disable a service account. Reversible only by deleting and re-creating. |
| `taskstation tokens service-accounts rm <id> [-y\|--yes]` | Delete a service account permanently. |

A personal API key acts as you and dies with your membership. A service
account acts as itself and inherits no access: a new one holds no permissions.
Grant it one with `taskstation access grant --service-account <id> --role <key>`.
`--expires <when>` takes ISO-8601 or a forward span: `30d`, `12h`, `6w`, `1y`.

### Billing

Read the active account's plan, credits, and spend. Read-only: plan changes,
top-ups, and payment methods are dashboard flows.

| Command | Effect |
| --- | --- |
| `taskstation billing status [--json]` | Plan, credits, seats, subscription. |
| `taskstation billing transactions [--limit <n>] [--offset <n>] [--type <a,b>] [--json]` | Credit ledger, newest first. Default page size 50. |
| `taskstation billing transactions --summary\|--breakdown\|--usage [--days <n>]` | Credits in/out, the balance split (expiring/non-expiring/daily), or a credit-usage summary. `--days` is the window for `--summary` and `--usage`; default 30. |
| `taskstation billing costs [--since <iso>] [--until <iso>] [--json]` | Account spend over a window, plus a model breakdown. Default window: 30 days, half-open `[from, to)` UTC. |
| `taskstation billing costs --by project\|session [--sort <k>] [--limit <n>] [--offset <n>] [--csv <file>]` | Roll spend up by project or by session. `--sort` takes `total_desc` (default), `total_asc`, `recent`, or `name_asc` (`--by project` only). `--csv` needs `--by`. |

Filters: `--project <id>`, `--session <id>`, and `--owner <id>` (sessions, with
`--by session`). Options: `--account <id>`, `--host <name>`, `--json`.

### Projects

A command resolves "the project" in this order:

1. The `--project` flag.
2. The `TASKSTATION_PROJECT_ID` environment variable.
3. `.taskstation/link.json` in the exact working directory.
4. The global default set by `taskstation projects use`.

| Command | Effect |
| --- | --- |
| `taskstation projects ls [--all] [--query <text>] [--json]` | List projects on the active account. `--all` spans every account you belong to. `--query` (alias `-q`) filters by name, id, or repo. |
| `taskstation projects info [<id>] [--json]` | Show one project. Default: the linked or default project. |
| `taskstation projects use [<id>]` | Set the global default project. Switches the active account if the project lives elsewhere. |
| `taskstation projects unset` | Clear the global default project. |
| `taskstation projects link [<id>]` | Bind the current directory to a project. Writes `.taskstation/link.json`. |
| `taskstation projects unlink` | Remove `.taskstation/link.json`. |
| `taskstation projects open [<id>]` | Open a project's dashboard page in your browser. |
| `taskstation projects clone [<id>] [dir]` | Clone a project's repo through the authenticated TaskStation git proxy. |
| `taskstation projects rm [<id>] [--purge] [-y\|--yes]` | Archive a project. `--purge` also deletes its managed git repo. |
| `taskstation projects set [<id>] [--name <n>] [--branch <b>] [--manifest <path>] [--json]` | Update one project's settings. Only the fields you pass are written. Passing no field exits `2`. Alias: `update`. |
| `taskstation projects set [<id>] --icon <emoji>\|--no-icon\|--glyph <name>:<color>\|--no-glyph` | Set or remove the project's icon. |
| `taskstation projects rename [<id>] <name>` | Alias for `taskstation projects set --name <name>`. |
| `taskstation projects features [ls] [--json]` | List every feature flag with its key, state, origin, and stability. |
| `taskstation projects features enable\|disable\|reset <flag>` | Set the project override on, off, or clear it so the flag follows the platform default. |
| `taskstation projects cli-tokens ls [--json]` | List the project's CLI tokens. |
| `taskstation projects cli-tokens new [--name <name>]` | Mint a project-scoped CLI token. The secret prints once. |
| `taskstation projects cli-tokens rm <token-id> [-y\|--yes]` | Revoke one project CLI token. |
| `taskstation projects upgrade [<id>] [--json]` | Start the agent session that migrates a v1 `taskstation.toml` to a v2 `taskstation.yaml` and opens a change request. |

A project shows one icon, so writing `--icon` clears the glyph and writing
`--glyph` clears the emoji; passing both is refused. Glyph colors: `grey`,
`red`, `orange`, `yellow`, `lime`, `blue`, `purple`, `magenta`. `set` and
`features` need `project.customize.write`. A flag the platform marks
unavailable stays off regardless of the project override.

A project CLI token is bound to one project — the API rejects it everywhere
else. A session sandbox uses its session-bound `TASKSTATION_TOKEN`. `cli-tokens ls`
needs project read; `new` and `rm` need
`project.credentials.issue`. An agent-session token can neither mint nor
revoke project tokens (`403`).

`taskstation projects upgrade` needs project write. The default agent refreshes the
marketplace baseline, rewrites the manifest, runs `taskstation validate`, and opens
a change request. It never merges: a human reviews the diff.

### Project scaffold

`taskstation init [project-name] [options]` creates a new project directory. The
starter writes a v2 `taskstation.yaml` and the canonical `.taskstation/opencode`
system-skill source. The command can wire local coding-tool discovery without
changing the cloud OpenCode runtime. The command does not write
`.taskstation/link.json`. `taskstation ship` or `taskstation projects link` create that file.

| Flag | Meaning |
| --- | --- |
| `--name <project>` | Project name. |
| `--primary <agent>` | Primary agent. |
| `--agents <csv>` | Local coding-agent integrations to wire up. |
| `--force` | Configure the current directory in place instead of scaffolding a new one. |
| `--overwrite` | Overwrite existing files. |
| `--no-git` | Skip git init. |
| `-y, --yes` | Don't prompt. |

The local coding-tool selection does not change the cloud OpenCode runtime.

`taskstation init` does not include a marketplace picker. Adding a marketplace skill is an agent import: start a session and ask the agent to bring one in.

### Ship

`taskstation ship` stages, commits, and pushes your current branch to the project's git repo. Run it once to create the project. Run it again any time to sync. Alias: `taskstation deploy`.

Each run:
- Parses and validates `taskstation.yaml` (skip with `--no-verify`).
- Commits any dirty working tree (skip with `--no-commit`).
- Prompts for any missing `env` secret (skip with `--no-env`).
- Pushes the current branch to the same-named remote branch.
- Connects any declared connector that still needs auth (skip with `--no-connect`).

An existing GitHub `origin` links through the TaskStation GitHub App. Any other existing `origin` is registered as-is. No `origin` creates a managed TaskStation git repo.

| Option | Effect |
| --- | --- |
| `--name <project>` | Display name for a new project. |
| `--account <id\|slug>` | Account to create the project under (first ship only). |
| `--origin <managed\|git-url>` | Override the inferred origin choice. |
| `--github-token <pat>` | Link a GitHub origin with this token instead of the GitHub App. |
| `-m, --message <text>` | Commit message. |
| `--no-commit` / `--no-verify` / `--no-env` / `--no-connect` | Skip that step. |
| `-y, --yes` | Don't prompt. |
| `-n, --dry-run` | Print what would happen; change nothing. |
| `--project <id>` / `--host <name>` | Target a non-default project or host. |

### Sessions

Each session runs in one sandbox on its own branch.

| Command | Effect |
| --- | --- |
| `taskstation sessions ls` | List every session on the project. |
| `taskstation sessions status [--all] [--json]` | Every session and what its agent is doing right now. Aliases: `overview`, `ps`. |
| `taskstation sessions info <id> [--json]` | Detail view: status, branch, agent, sandbox URL. |
| `taskstation sessions new [--prompt "<text>"] [--agent <name>] [--model <id>] [--wait] [--connect] [--json]` | Start a session. `--connect` attaches the OpenCode TUI once it is ready (implies `--wait`); on an interactive terminal without it, the CLI asks whether to connect after creation. `--model <id>` overrides the project's default model. `--wait` blocks until it is running (up to ~5 minutes). Use `--secret <id>` or `--no-secrets` to narrow Secret access. These Secret flags require a backend token. Use `--connector <alias>=<authorization-id>` or `--no-connectors` to set Connector access. Use `--require-connector <alias>` to require an authorization before provisioning. Scope flags are repeatable. Use `--context <key>=<value>` for non-secret runtime context. |
| `taskstation sessions chat [<id>] [--prompt "<text>"] [--queue] [--new] [--agent <name>] [--json]` | Talk to a session's agent. Interactive by default. Alias: `talk`. Top-level `taskstation chat` also works. `--queue` is one-shot only: it stores the prompt in the session's durable inbox and returns as soon as it is stored, instead of handing it to the runtime. |
| `taskstation sessions connect [<id>] [-- <opencode args>]` | Attach the OpenCode TUI to the session's OpenCode server. Also available top-level: `taskstation connect` / `taskstation attach`. With no id, opens a session picker (running, stopped-with-restart, or new). The CLI auto-downloads the version-matched `opencode` binary (cache: `~/.taskstation/opencode/<version>/`; override: `TASKSTATION_OPENCODE_BIN`). |
| `taskstation sessions shell [<id>] [--new]` | Open a raw interactive terminal in the sandbox, with no agent. Reattaches to the session's existing terminal; `--new` always starts a fresh one. Aliases: `terminal`, `ssh`. |
| `taskstation sessions shell <id> ls [--json]` | List the session's terminals: id, status, command. Needs no TTY. |
| `taskstation sessions shell <id> kill <pty-id>` | Kill one terminal. The ambient shell respawns on the next attach; anything running inside it does not. |
| `taskstation sessions log [<id>] [--limit <n>] [--json]` | Print recent messages, read-only. Aliases: `messages`, `history`. |
| `taskstation sessions pending <id> [--json]` | List open tool-permission or question prompts. Alias: `prompts`. |
| `taskstation sessions approve <id> [<req-id>] [--always] [--reject] [--message "<text>"]` | Answer a permission prompt. |
| `taskstation sessions answer <id> [<req-id>] [--option <v>]... [--text "<text>"] [--reject]` | Answer a question prompt. |
| `taskstation sessions digest [--since <7d>] [--json]` | Compact multi-session review. Aliases: `review`, `summary`. |
| `taskstation sessions scope <id> [scope options] [--json]` | Read or replace Secret and Connector access. Alias: `access`. Use `--secret <id>`, `--no-secrets`, or `--inherit-secrets` for Secrets. Use `--connector <alias>=<authorization-id>` or `--no-connectors` for Connector bindings. Use `--require-connector <alias>` or `--no-required-connectors` for required Connectors. Provided categories replace their current values. Omitted categories remain unchanged. Changes apply to the next prompt. Removed Secret values remain in existing context if the session already read them. |
| `taskstation sessions preview <id> [port] [--port <n>] [--list] [--json]` | Print a clickable preview URL for a sandbox port. Default port: `3000`. `--list` prints the named candidates instead. |
| `taskstation sessions restart <id>` | Restart the session's sandbox. |
| `taskstation sessions rename <id> <name>` | Set a session's name. Pass `""` to clear it. |
| `taskstation sessions rm <id>...` | Stop and delete one or more sessions. |
| `taskstation sessions open <id>` | Open a session's dashboard page in your browser. |
| `taskstation sessions stop <id> [--json]` | Pause a session. The sandbox stops in place and the disk is kept. Alias: `pause`. Needs `project.session.stop`. |
| `taskstation sessions start <id> [--wait] [--json]` | Wake a session: provision a missing sandbox, resume a stopped one, and resolve its runtime. Idempotent. Alias: `wake`. `--wait` blocks until ready (up to ~5 min) and exits `1` if the session ends up failed or stopped. |
| `taskstation sessions warm [--exclude <id>] [--json]` | Pre-create the session you are about to use, so the sandbox is already up. Reuses an existing unused warm session. A warm session stays hidden from `sessions ls` until its first prompt. |
| `taskstation sessions model <id> <model-id> [--json]` | Change the model a session runs, mid-session. A live sandbox is re-pointed and its runtime restarts, which ends the turn running right now; a stopped session stores the value for its next start. |
| `taskstation sessions compact <id> [--json]` | Summarize the conversation so far and continue from the summary. |
| `taskstation sessions queue <id> [ls] [--json]` | List the prompts still waiting in the session's durable inbox. |
| `taskstation sessions queue <id> rm <prompt-id>` | Drop one queued prompt. Refused (`409`) once a model step has started answering it. |
| `taskstation sessions queue <id> now <prompt-id>` | Run one queued prompt next: re-queue it ahead of the ordering rule and release the session's hold. |
| `taskstation sessions queue <id> hold\|release` | Hold every queued prompt — what the Stop button writes — or release the hold. |
| `taskstation sessions approvals <id> [ls] [--json]` | List the governed connector calls this session is waiting on a human for. |
| `taskstation sessions approvals <id> approve\|deny <execution-id>` | Let one governed connector call run, or refuse it. The agent is told and continues without it. |
| `taskstation sessions files <id> <subcommand> [--json]` | Read and edit the sandbox's live workspace: `ls [<path>]`, `status`, `find <query>`, `write <path>`, `touch <path>`, `mkdir <path>`, `mv <from> <to>`, `rm <path>`. |
| `taskstation sessions share <id> [--mode private\|project\|members] [--member <id\|email>] [--group <id>] [--show] [--json]` | Set who inside TaskStation can open this session. With no `--mode` it prints the current setting and changes nothing. `--member` and `--group` are repeatable. |
| `taskstation sessions links <id> ls [--json]` | List every public link ever minted on the session, newest first. |
| `taskstation sessions links <id> create [options]` | Mint one public, unauthenticated link onto a preview port or one workspace file. |
| `taskstation sessions links <id> revoke <share-id>` | Kill one public link. |

`sessions queue` needs `project.session.start` — the same permission as sending
a message. A queued prompt survives a closed terminal and is delivered when the
session can take it. Put one there with
`taskstation sessions chat <id> -p "…" --queue`.

`sessions approvals` are durable: unlike `sessions pending`, they survive a
sandbox restart. It needs `project.members.manage`, or being the human who
launched the session. An agent may never resolve its own approval.

`sessions files` reads the working tree the agent is editing right now, before
anything is committed; `taskstation files` reads the committed repo instead. Paths
resolve under `/workspace` unless they start with `/workspace`, `/tmp`,
`/home`, or `/opt`. The command wakes the sandbox if it is asleep. Options:
`--from <local path>` (`write` reads this file instead of stdin), `--content`
(`find` greps contents with ripgrep instead of filenames), `--limit <N>`
(`find` filename cap), and `-y` to skip the `rm` confirmation.

`sessions share` is owner-governed: the API refuses a project manager who
cannot already read the session.

`sessions links create` options: `--port <n>` (default `3000`; `22`, `8000`,
and the opencode ports are refused), `--path <p>` (default `/`),
`--preview <id>` (a named candidate — `web`, `vite`, `dev-server`, `api-docs` —
instead of `--port`/`--path`), `--file <path>` (share one workspace file
instead of a preview; always read-only), `--mode view\|interactive` (default `view`;
`interactive` allows writes and websockets, and is ignored for `--file`),
`--label <text>`, and `--expires <iso>`. Minting a link needs the session
owner, because the link itself needs no login; listing and revoking also accept
a project manager.

Inside a sandbox, `TASKSTATION_SESSION_ID` is your own session's id.

### Change requests

A change request (CR) merges one branch into another on any git host. It is the only way for an agent to land session work on the default branch. See [Change requests](/docs/work/change-requests).

| Command | Effect |
| --- | --- |
| `taskstation cr ls [--status open\|merged\|closed\|all] [--project <id>]` | List CRs. Default: `--status open`. |
| `taskstation cr show <cr> [--project <id>]` | Show one CR, including its merge preview. Alias: `info`. |
| `taskstation cr diff <cr> [--no-color] [--json]` | Print a CR's unified diff. |
| `taskstation cr open --title "<text>" [--description "<text>"] [--head <ref>] [--session <id>] [--base <ref>]` | Open a CR. Aliases: `new`, `create`. Inside a sandbox, `--head` and `--session` default automatically. `--base` defaults to the project's default branch. |
| `taskstation cr merge <cr> [--message "<text>"]` | Merge an open CR. Fast-forward when possible, three-way merge otherwise. |
| `taskstation cr close <cr>` | Close an open CR without merging. |
| `taskstation cr reopen <cr>` | Reopen a closed CR. Merged CRs are terminal. |
| `taskstation cr merge-preview <cr> [--json]` | Report whether the CR can merge, and list every conflicting path. Alias: `preview`. |
| `taskstation cr request-changes <cr> --message "<text>"` | Ask the agent that opened the CR to revise it. Alias: `changes`. |
| `taskstation cr version-diff --from <ver> --into <ver> [--json]` | Summarize one version against another before opening a CR. |

`request-changes` records the note on the CR and delivers it to the originating
session, booting its sandbox if it is asleep. It needs `project.review.act` —
the same leaf the Review Center uses, not `gitops.push`.

`<cr>` accepts a per-project number (`3`) or the full id. Inside a sandbox, the CLI reads its token automatically — no login or link needed.

### Review

The project's review inbox — everything waiting on a human decision: change
requests, connector tool calls a policy gated for approval, and the outputs,
decisions, and batches agents submit for sign-off. Mirrors the dashboard's
Review Center. Gated by the `review_center` feature flag; turn it on with
`taskstation projects features enable review_center`.

| Command | Effect |
| --- | --- |
| `taskstation review ls [--segment <s>] [--kind <k>] [--json]` | List inbox items. Default: every segment. |
| `taskstation review show <item-id> [--json]` | Show one item in full. |
| `taskstation review act <item-id> <verdict> [--message <text>]` | Decide one item. `--message` carries the note. |
| `taskstation review bulk <verdict> <id> [<id> …]` | Decide several native items in one call. |
| `taskstation review submit --kind <k> --title <t> [options]` | Submit an output, decision, or batch for review. |

Verdicts: `approve`, `reject`, `changes`, `answer`, `dismiss`. Segments:
`needs_you`, `waiting`, `done`. Kinds: `change`, `approval`, `output`,
`decision`, `batch`.

Where a verdict lands depends on the item id. On `cr:<id>`, `approve` merges
the change, `reject` closes it, and `changes` sends the note back to the agent
that opened it (`--message` required). On `call:<id>`, `approve` lets the tool
call run and `reject` denies it; a connector approval takes no other verdict —
read its arguments first with `taskstation review show`. Every other id goes to the
native act endpoint, which takes every verdict.

`bulk` acts on native ids only. A connector approval needs its own parameter
review and a change request needs its diff in view, so both are reported and
skipped — the same rule as the dashboard's multi-select.

`submit` options: `--kind output\|decision\|batch` (required), `--title <text>`
(required), `--summary <text>`, `--risk none\|low\|medium\|high` (default
`none`), `--detail <json>` (a JSON object), `--agent <name>`, and
`--session <id>` (ignored when it is not this project's session).

Reads need `project.review.read`, verdicts need `project.review.act`, and
`submit` needs `project.review.submit`.

### Secrets

Encrypted values stored on the project. By default a secret injects as a plain environment variable into every session sandbox at boot (environment exposure). Enforced delivery — where the sandbox holds a handle and TaskStation substitutes the real value outside it (egress-enforced exposure, and `taskstation secrets call`) — is experimental. Enable the `secrets_egress` feature flag (Settings → Feature flags) to use it; with the flag off, `taskstation secrets delivery … egress` returns `403` `feature_disabled`. See [Secrets](/docs/project/secrets).

| Command | Effect |
| --- | --- |
| `taskstation secrets ls` | List secrets by identifier and manifest `env` spec. Marks required-but-missing values. |
| `taskstation secrets set NAME=VALUE ... [--identifier <id>]` | Upsert one or more secrets. `NAME=-` reads the value from stdin. |
| `taskstation secrets request NAME ... [--scope runtime\|connector] [--expires <min>]` | Mint a link for a human to enter a value directly — you never see the raw value. |
| `taskstation secrets unset NAME ...` | Remove secrets. |
| `taskstation secrets grant IDENTIFIER --agent <name>` | Let one agent receive this secret: merge the identifier into that agent's `secrets` list in `taskstation.yaml`, adding the agent entry when the manifest omits it. |

`grant` is the fix for a row `ls` reports as undeliverable. It only ever widens
one agent's list; to narrow or replace it, rewrite the whole set with `taskstation
agents scope`. There is no `secrets revoke` — the API has no route that removes
a single identifier from a grant. The first grant on a project with no agents
starts governance: from then on, an agent the manifest does not list receives
no project secrets, and the command says so when it happens.

### Env

| Command | Effect |
| --- | --- |
| `taskstation env pull [--out <path>] [--force]` | Write a `.env` skeleton — names only. Values never leave the cloud. |
| `taskstation env push --from <path>` | Upload every `NAME=VALUE` from a dotenv file as a secret. |

### Agents

Per-agent model settings on the linked project.

| Command | Effect |
| --- | --- |
| `taskstation agents ls [--json]` | Show every agent's pinned model and the fallback default. Alias: `models`. |
| `taskstation agents model <agent> <provider/model>` | Pin an agent to a model. |
| `taskstation agents model <agent> --clear` | Clear the pin — the agent follows the default again. |
| `taskstation agents default <agent>` | Make this the project's default agent. |
| `taskstation agents default --show [--json]` | Print the current default agent. |
| `taskstation agents scope <agent> [--secrets all\|none\|A,B] [--connectors all\|none\|a,b] [--require-connector <slug>]` | Replace which secrets and connectors the agent may use. `--require-connector` is repeatable and must resolve before a session starts. |
| `taskstation agents scope <agent> --show [--json]` | Print the agent's current scope. |
| `taskstation agents config <agent> [--json]` | Print the full agent config block. |
| `taskstation agents config <agent> --file <path>` | Replace the block with a JSON file's contents. `-` reads stdin. |
| `taskstation agents config <agent> --set <key>=<value> ...` | Change single dotted keys, merged in. Repeatable, e.g. `opencode.model=glm-5.3-flash`, `enabled=false`, `connectors=["slack"]`. |

Every scope option replaces; none merge. A `--set` value is parsed as JSON when
it parses, and kept as a string otherwise. Model pins and `scope` apply
instantly, with no `taskstation.yaml` commit; `default` and `config` commit to
`taskstation.yaml` on the project's default branch. `scope` needs
`project.agent.write`; `default` and `config` need `project.customize.write`.

### Models

Which models the project offers, and which one it starts with. Same surface as
the dashboard's Customize → Models. A project stores only its exceptions to the
catalog default (the newest model of each family). Enablement is display-only:
it decides what pickers offer, never what the gateway serves.

| Command | Effect |
| --- | --- |
| `taskstation models ls [--json]` | List every model: state, origin, provider. |
| `taskstation models enable <model-id>...` | Offer these models. |
| `taskstation models disable <model-id>...` | Stop offering them. The project default refuses with `409` — change the default first. |
| `taskstation models reset` | Drop every exception; back to the catalog default. |
| `taskstation models default [--json]` | Print the default chain (project → account → platform) and what it resolves to. |
| `taskstation models default <model-id> [--account]` | Set the project default, or the account-wide one with `--account`. |
| `taskstation models default --clear [--account]` | Clear the project, or account, default. |

Model ids are gateway wire ids — a bare managed id (`glm-5.3-flash`) or a BYOK
`provider/model`. Copy one from `taskstation models ls --json`. Per-agent pins live
on `taskstation agents model <agent> <model-id>`. Writes need
`project.customize.write`.

### Channels

Manages the project's connection to a chat platform. Tokens are stored encrypted in the project's secrets and resolved server-side — they are never injected into the sandbox.

| Command | Effect |
| --- | --- |
| `taskstation channels status [--json]` | Show the current connection. |
| `taskstation channels connect [--wait] [--timeout <sec>]` | Connect in one step: prints an install link. `--wait` polls until the install lands. |
| `taskstation channels connect --manual [--bot-token <token>] [--signing-secret <secret>]` | Bring-your-own-app mode: save a bot token and signing secret directly. |
| `taskstation channels disconnect [--platform slack\|teams]` | Drop the project's connection — the Slack one, or the Teams one with `--platform teams`. |
| `taskstation channels manifest` | Print the app manifest JSON for the bring-your-own-app path. |
| `taskstation channels email status [--json]` | Inbox and delivery mode for one email connector. |
| `taskstation channels email connect [options]` | Create a managed inbox, or attach an existing AgentMail one. |
| `taskstation channels email disconnect` | Drop the inbox connection. |
| `taskstation channels email policy [--allow <email\|@domain>] [--allow-regex <re>] [--allow-all]` | Replace who may email the agent. |
| `taskstation channels bindings [ls] [--json]` | List every bound channel and the agent, model, and join policy it resolves to. |
| `taskstation channels bind <bindingId> [--agent <name>\|--no-agent] [--model <id>\|--no-model] [--policy <p>]` | Change one binding. `--policy` takes `owner_approval`, `owner_only`, or `project_open`. |
| `taskstation channels voice name <text>` | Set the display name the voice bot joins calls with. |
| `taskstation channels voice name --show` | Print the current voice bot name. |

`--platform slack|teams` selects the platform; default `slack`. Teams
`connect` prints the Microsoft admin-consent URL; granting tenant-wide consent
publishes the app to your Teams catalog automatically. See [Connectors](/docs/connect/connectors).

The email channel is AgentMail-backed and needs the `agentmail_email` feature
flag. `email connect` options: `--connector <slug>` (default `taskstation_email`),
`--api-key <k>` (bring your own AgentMail key; `-` reads stdin),
`--display-name <n>` (from-name on outgoing mail; default the project name),
`--username <u>` and `--domain <d>` (a new managed inbox), and
`--inbox-id <id>` with `--email <addr>` (attach an existing inbox — both are
required together). `--allow` is repeatable and puts the policy in restricted mode; a
bare value with no `@`, or one with a leading `@`, is read as a domain.
`--allow-all` clears the list and accepts every sender again.

Email and `bind` writes need `project.connector.write`. `voice name` needs
`project.customize.write`.

### Connectors

Connectors an agent calls as tools. `add`, `rm`, and `policy set` edit the local `taskstation.yaml`; run `taskstation ship` to apply, unless you pass `--apply` to change the cloud project immediately.

| Command | Effect |
| --- | --- |
| `taskstation connectors ls [--json]` | List connectors and their status. |
| `taskstation connectors show <slug> [--json]` | Show one connector's tools. |
| `taskstation connectors add <slug> --provider <p> [options] [--apply]` | Add a connector. |
| `taskstation connectors rm <slug> [--apply]` | Remove a connector. |
| `taskstation connectors rename <slug> <name>` | Set a connector's display name. |
| `taskstation connectors sync` | Reconcile the catalog from the shipped `taskstation.yaml`. |
| `taskstation connectors credential <slug> [value]` | Set a connector's credential. |
| `taskstation connectors connect <slug>` | Start a one-click connect flow. |
| `taskstation connectors link <slug> [--expires <min>]` | Mint a shareable connect link for a human. |
| `taskstation connectors apps [<query>] [--category <c>] [--cursor <c>] [--json]` | Browse the Pipedream app catalog. |
| `taskstation connectors catalog [<query>] [--cursor <c>] [--json]` | Browse the direct-connector catalogue. Needs the `connectors_api_discover` flag. |
| `taskstation connectors catalog show <id> [--json]` | Show one catalogue record's surfaces. |
| `taskstation connectors sensitive <slug> on\|off` | Gate this connector's reads too — every call then needs approval. Applies now. |
| `taskstation connectors owner <slug> project\|user` | Who authorizes: one project connection, or each member's own. Applies now. |
| `taskstation connectors machines <slug> [--show] [--add <id>] [--rm <id>]` | Which paired computers a `computer` connector may target. Applies now. |
| `taskstation connectors authorize <slug> [--status] [--scope "<a b>"] [--client-id <id>] [--client-secret <s>] [--success-redirect <url>] [--error-redirect <url>] [--json]` | OAuth 2.1 a connector end to end: discover the server's authorization metadata, register TaskStation as a client (RFC 7591) where the server supports it, and print the URL to approve. `--status` reports the result instead. |
| `taskstation connectors authorize <slug> --device` | Same, using the OAuth 2.0 device flow (RFC 8628): print a code and a URL, then poll until it is approved, denied, or expired. |
| `taskstation connectors policy ls [--json]` | Show project-wide execution policy. Alias: `show`. |
| `taskstation connectors policy set --default <risk\|allow_all> [--apply]` | Set the default execution mode in `taskstation.yaml`. `--apply` sets it live instead. |
| `taskstation connectors policy add <match> <allow\|ask\|block> [--condition <k=v>]` | Add a project-wide rule. Applies now. `--condition` narrows it to a matching argument and is repeatable; `k!=v` negates, and `k` is a dot path into the call's arguments. |
| `taskstation connectors policy rm <match>` | Remove a project-wide rule. Applies now. |
| `taskstation connectors policy <slug> ls\|set <match> <allow\|ask\|block>\|rm <match>\|clear` | Manage one connector's tool-call rules. |

`policy ls`, `show`, `set`, `add`, and `rm` are the project-wide surface, so a
connector named after one of those verbs must be addressed as
`policy <slug> ls`. A `<match>` is a tool name, a glob (`send_*`), or a `/regex/`.

`add` options: `--name <label>`, `--provider <pipedream\|mcp\|openapi\|postman\|graphql\|http>`, `--app <slug>`, `--url <url>`, `--transport <http\|sse>`, `--endpoint <url>`, `--base-url <url>`, `--spec <url\|path>`, `--auth-type <none\|bearer\|basic\|custom>`, `--credential shared`.

### Sandboxes

Manages the project's sandbox images. A template defines an image or Dockerfile plus resources; a build produces the snapshot sessions boot from.

| Command | Effect |
| --- | --- |
| `taskstation sandboxes ls [--json]` | List templates and live provider state. |
| `taskstation sandboxes builds [--json]` | Recent build log. |
| `taskstation sandboxes health [--json]` | Primary template readiness. |
| `taskstation sandboxes add <slug> (--image <i>\|--dockerfile <p>) [options]` | Create a custom template and start a build. |
| `taskstation sandboxes update <slug> [options]` | Update a template. |
| `taskstation sandboxes build <slug>` | Trigger a rebuild. |
| `taskstation sandboxes rebuild <slug>` | Force-rebuild: delete the existing snapshot first. |
| `taskstation sandboxes rm <slug>` | Delete a template. |
| `taskstation sandboxes fix` | Start a session seeded with the last failed build log, to repair it. |
| `taskstation sandboxes provider [--json]` | Show the project's sandbox-provider pin and which providers this host offers. |
| `taskstation sandboxes provider <name> [--timeout <sec>]` | Pin every new session to one provider. Where the target needs its snapshot built first, the API answers with a preparation and the command follows it to completion. Default `--timeout`: 600s. |
| `taskstation sandboxes provider --clear` | Drop the pin and follow the platform default. Alias: `--unpin`. |
| `taskstation sandboxes provider status [--json]` | Show the latest provider transition and its history. Alias: `transition`. |

Pinning a provider needs `project.customize.write`.

`add`/`update` options: `--name <label>`, `--cpu <n>`, `--memory <n>` (GiB), `--disk <n>` (GiB).

### Marketplace

Browse the TaskStation marketplace, and install an item into a project.

| Command | Effect |
| --- | --- |
| `taskstation marketplace search [query]` | Search marketplace items. |
| `taskstation marketplace list` | List marketplace items. |
| `taskstation marketplace show <id-or-name>` | Show one marketplace item. |
| `taskstation marketplace install <id-or-name>` | Start an agent session that imports the item. |

Options: `--query <text>`, `--type <type>`, `--source <source>`, `--host <name>`, `--project <id>`, `--json`.

Install is agent-driven: it starts a project session that clones the item,
reads it, merges what fits, and opens a change request. There is no
deterministic install/update/remove machinery.

### System skills

The TaskStation system skills are the platform's own documentation. They cover
sessions, sandboxes, OpenCode, the connector, memory, and
channels. The API serves them live, so they match the deployed host version.
The binary and a token are enough for an agent to retrieve this context.

| Command | Effect |
| --- | --- |
| `taskstation system-skills list` | List the TaskStation system skills. Default subcommand. |
| `taskstation system-skills get <name> [--full]` | Print one skill's current `SKILL.md`. `--full` adds its referenced files. |
| `taskstation system-skills path [name]` | Print a skill's on-disk directory in this project. |

Options: `--host <name>`, `--json`.

`taskstation skills` is a permanent alias for the same command.

This list is always the system skills, never a mix. Optional skills live in the marketplace: `taskstation marketplace list --type skill`.

### Connector

The in-sandbox agent's interface to every connector. Every call is checked, resolved, and audited server-side; the CLI never holds a third-party credential. Auth: `TASKSTATION_TOKEN`. Output is JSON.

| Command | Effect |
| --- | --- |
| `taskstation connectors discover "<intent>"` | Search tools by natural-language intent. |
| `taskstation connectors show <connector>.<action>` | Show an action's input schema. |
| `taskstation connectors call <connector>.<action> '<json-args>'` | Run a tool. A governed call returns its authenticated `approval_url` immediately. The server resumes the session after one approve or deny decision. |
| `taskstation connectors add <slug> --provider pipedream --app <app>` | Add a connector immediately, then connect it. |
| `taskstation connectors rm <slug>` | Remove a connector from the project. |
| `taskstation connectors connect <slug>` | Mint a connect link for a human. |
| `taskstation connectors mcp` | Run the optional stdio MCP compatibility server. |

### Files

Read-only view of the project's git repo. Operates on the default branch unless `--ref` names another branch, tag, or commit.

| Command | Effect |
| --- | --- |
| `taskstation files ls [<path>]` | List files under a path. |
| `taskstation files cat <path>` | Print a file's contents. |
| `taskstation files search <query> [--content]` | Search filenames, or file contents with `--content`. |
| `taskstation files history <path>` | Commit history for one file. |
| `taskstation files branches` | List branches. |
| `taskstation files commits [--path <p>]` | List commits on `--ref`. |
| `taskstation files show <sha>` | Show one commit and its changed files. |
| `taskstation files diff <sha> [--path <p>]` | Print a commit's unified patch. |
| `taskstation files compare <from> <into>` | Summarize the diff between two refs. |
| `taskstation files download -o <out.zip>` | Download the repo, or the `--path` subtree, at `--ref` as a zip. Alias: `archive`. |

Options on every subcommand: `--ref <ref>`, `--path <p>`, `--limit <n>`, `--json`.
`download` also takes `-o, --out <file>`, which is required.

Every subcommand needs `project.file.read`. `download` additionally refuses any
subtree that would include an agent or skill you are scoped out of — a zip
cannot be filtered mid-stream — so archive a narrower `--path` in that case.

### Triggers

A trigger starts a session from a schedule, a webhook, or a monitor (experimental). `add`, `rm`, `enable`, `disable` edit the local manifest — run `taskstation ship` to apply. `pause`/`resume` flip a separate, server-side switch. See [Triggers](/docs/connect/triggers).

| Command | Effect |
| --- | --- |
| `taskstation triggers ls [--json]` | List triggers and their runtime state. |
| `taskstation triggers add <slug> [options] [--apply]` | Append a trigger to the manifest. `--apply` creates it on the cloud project now instead: it commits to `taskstation.yaml` on `main` and reconciles. |
| `taskstation triggers set <slug> [options]` | Change a live trigger. Only the flags you pass are written. Always applies now — there is no local form. Alias: `update`. |
| `taskstation triggers rm <slug> [--apply]` | Remove a trigger from `taskstation.yaml`, or from the cloud project now with `--apply`. |
| `taskstation triggers info <slug> [--json]` | Show one trigger. |
| `taskstation triggers fire <slug>` | Fire a trigger manually. |
| `taskstation triggers enable <slug> [--apply]` / `disable <slug> [--apply]` | Turn one trigger on or off. |
| `taskstation triggers pause` / `resume` | Deactivate or reactivate every trigger on the project, server-side. |

`add` options: `--type <cron\|webhook\|monitor>` (default `cron`), `--prompt <text>` (required), `--agent <name>`, `--cron <expr>` (6-field, e.g. `"0 0 9 * * 1-5"`), `--run-at <iso>` (run once at this instant instead of on a cron), `--timezone <tz>` (default UTC), `--secret-env <NAME>`, `--name <label>`, `--disabled`.

Live-only options — valid on `add --apply`, and on every `set`: `--model <provider/model>`, `--session-mode <fresh\|keyed\|pinned\|reuse>`, `--session-key <tmpl>` (bucket one session per key, e.g. `"{{ body.data.chat_jid }}"`; implies `keyed`), `--session-id <id>` (the session a `pinned` trigger loops; must be this project's session), `--session-access <private\|project\|members>` (default `private`), `--member <uuid>` and `--group <uuid>` (repeatable; each implies `members`), and `--filter <path=value>` (repeatable; every one must match, e.g. `--filter body.type=push`).

`set` takes every live-only option plus `--name`, `--prompt`, `--cron`, `--run-at`, `--timezone`, `--secret-env`, `--agent`, and `--enabled true|false`. `--cron` and `--run-at` are exclusive: setting one clears the other. Monitor fields are add-only.

Monitor options (`--type monitor`): `--run <cmd>` (repo-relative command to supervise; required), `--mode <poll\|stream>` (required; `poll` re-runs on `--interval`, `stream` keeps the command alive), `--interval <dur>` (`mode=poll` only, minimum 30s, e.g. `60s`, `5m`), and `--expect-event-within <dur>` (silence watchdog; no event inside the window fires a lifecycle event instead, minimum 5m, e.g. `24h`). A monitor is a repo command the platform runs 24/7, and each stdout line fires the trigger. It is experimental: the platform runs monitors only where the `monitors` feature flag is on.

### Access

The CLI face of the one grant table. Every row is an **assignment**: one
principal, one role, one scope, optionally narrowed to one object. See
[Accounts & access](/docs/accounts#one-access-model) for the model. Account
roles: `owner`, `admin`, `member`. Project roles: `manager`, `member`.

| Command | Effect |
| --- | --- |
| `taskstation access assignments [--project <id>\|--account\|--all] [--json]` | List assignments at one project, at the account, or everywhere. |
| `taskstation access grant --user <id\|email>\|--group <id>\|--service-account <id> --role <key\|id> [opts]` | Create one assignment. Prints the assignment id. |
| `taskstation access revoke <assignment-id>` | Revoke one assignment. |

Grant options: `--project <id>` (default: the linked project), `--account` (the
whole account), `--agent <name>` (narrow the grant to one agent — an object
assignment), and `--expires <iso>` (auto-revoke timestamp). `--principal` filters
a list, and takes `user:<id>`, `group:<id>`, `service_account:<id>`, or
`pending:<email>`; a bare id is read as a user. An agent's identity is a
`service_account`, so `--service-account <id>` is how you assign a role to an
agent. `--user` accepts an email and resolves it against the account member
directory.

```bash
taskstation access grant --user alice@corp.com --role manager
taskstation access grant --user alice@corp.com --role admin --account
taskstation access grant --group 8f3c… --role member --project 1a2b…
taskstation access grant --user alice@corp.com --agent support-bot
taskstation access revoke 4d5e…
```

The project member verbs are a read model over the same assignments:

| Command | Effect |
| --- | --- |
| `taskstation access ls [--json]` | List the people with project access, their account role, and their effective project role. |
| `taskstation access invite <email> --role <r>` | Invite someone to the project. Creates a `pending` assignment. |
| `taskstation access grant <user-id> --role <r>` | Set a user's project role. |
| `taskstation access revoke <user-id>` | Remove a user's project access. |
| `taskstation access pending [--json]` | List pending invitations. |
| `taskstation access resend <invite-id>` | Re-send an invite email and refresh its 14-day expiry. Prints the link too. |
| `taskstation access cancel <invite-id>` | Cancel a pending invitation. |
| `taskstation access requests ls [--json]` | List the pending requests from people asking to join this project. |
| `taskstation access requests approve <req-id> [--role <r>]` | Approve one request, granting the project role. Default role: `member`. |
| `taskstation access requests reject <req-id>` | Reject one request. Alias: `deny`. |

Every verb in the two blocks above needs `project.members.manage`.

A person, a group, or an agent gets roles from TaskStation; an agent additionally
carries TaskStation CLI scopes in `taskstation.yaml`, and a session can only do what both
allow. See [One vocabulary, two bindings](/docs/accounts#one-vocabulary-two-bindings).

### Audit

The audit commands read the centralized reconstruction log. Account and project
lists are newest first. A session timeline is ordered by its monotonic
`session_sequence`. `--all` follows every continuation cursor.

| Command | Effect |
| --- | --- |
| `taskstation audit ls [filters] [--all] [--json]` | List account events. |
| `taskstation audit project <project-id> [filters] [--all] [--json]` | List one project's events. |
| `taskstation audit session <session-id> --project <project-id> [--all] [--json]` | Reconstruct one session in order. |
| `taskstation audit export [filters] --format csv\|jsonl --out <file>` | Resume every export page into one file. |
| `taskstation audit webhooks ls [--json]` | List the account's audit webhooks. |
| `taskstation audit webhooks add --name <n> --url <u> [--action-prefix <p>]` | Create one. The signing secret prints once, and a test delivery fires immediately. `--action-prefix` delivers only actions with that prefix. |
| `taskstation audit webhooks enable <webhook-id>` | Resume delivery. |
| `taskstation audit webhooks disable <webhook-id>` | Pause delivery, keeping the endpoint. |
| `taskstation audit webhooks rm <webhook-id>` | Delete a webhook permanently. |

Audit webhooks stream the trail to a SIEM. Every verb needs `account.write`;
`add` and `enable` also need the enterprise entitlement. `disable` and `rm`
never do.

Filters: `--actor`, `--actor-type`, `--project`, `--session`, `--source`,
`--phase`, `--outcome`, `--action`, `--resource-type`, `--request-id`,
`--correlation-id`, `--query`, `--since`, `--until`, `--cursor`, and `--limit`.
Account lists and exports require `audit.read` and the account's `auditAccess`
entitlement. Project-wide lists require `project.members.manage` because they can
include private-session metadata. Session reconstruction requires
`project.session.read` and visibility of that session.

### Roles

A role is a named set of permissions. System roles (`owner`, `admin`, `member`
at account scope; `manager`, `member` at project scope; plus `agent-user`, the
marker an object assignment carries) are read-only references. Custom roles are
yours to create and edit, and need the enterprise `rbac` entitlement.

| Command | Effect |
| --- | --- |
| `taskstation roles ls [--json]` | List roles, system and custom. |
| `taskstation roles show <role> [--json]` | Show one role's permissions and usage. |
| `taskstation roles permissions <role> [--json]` | List one role's permissions. |
| `taskstation roles create <key> --name <n> [options]` | Create a custom role. |
| `taskstation roles edit <role> [--name <n>] [--desc <t>\|--no-desc]` | Rename or re-describe a custom role. Its key never changes. Needs `role.update`, and refuses a system role. |
| `taskstation roles set-actions <role> --actions a,b` | Replace a custom role's permissions. |
| `taskstation roles rm <role>` | Delete a custom role. |
| `taskstation roles export [--project <id>] [--out <file>] [--format toml\|json]` | Dump roles and assignments to a file. |
| `taskstation roles import <file>` | Apply a roles and assignments file. |

Bind a role to a principal with `taskstation access grant`. The older `taskstation roles
assign` / `unassign` / `assignments` verbs still work and write the same table,
but `taskstation access` is the documented path. `taskstation roles actions` is superseded
by `taskstation permissions ls`.

A custom role only adds permissions. TaskStation has no deny rule, so a role cannot
withhold a permission from a manager.

### Permissions

The permission catalog, as data. One row per leaf action, with the scope it is
decided at, whether it is delegable, and what it implies. Roles are built from
these keys — `taskstation roles create --actions` and `taskstation roles set-actions` take
exactly them. Alias: `taskstation perms`.

| Command | Effect |
| --- | --- |
| `taskstation permissions ls [--scope account\|project] [--area <a>] [--json]` | List the catalog. |
| `taskstation permissions show <action> [--json]` | Show one action in full. |

### Grants

Assigns one project object to a principal — an **object assignment**. Secrets and
connectors live on agents, so assigning an agent to a person grants everything
that agent declares. An agent is closed by default: a member reaches it only when
an assignment names them or one of their groups. `taskstation access grant --agent
<name>` writes the same row.

| Command | Effect |
| --- | --- |
| `taskstation grants ls [--json]` | List object assignments, and which agents can be assigned. |
| `taskstation grants assign <agent-name> --to <who> [--group]` | Assign an agent to a user, or to a group with `--group`. |
| `taskstation grants revoke <grant-id>` | Revoke one object assignment. |

### Manifest validation

| Command | Effect |
| --- | --- |
| `taskstation validate [--file <path>] [--json] [--scopes]` | Validate the manifest against the canonical schema. Resolves `taskstation.yaml` first, then `taskstation.toml`. Exit codes: `0` valid, `1` errors, `2` file missing. |
| `taskstation schema [--version 1\|2] [--url]` | Print the manifest's JSON Schema. `--url` prints the schema URL instead. |

See [Manifest reference](/docs/project/manifest).

### Self-host

`taskstation self-host` runs one Docker-based stack, identical on a laptop, a VPS, or a cloud VM. See [Self-hosting](/docs/host) and [Self-hosting architecture](/docs/host/architecture).

| Command | Effect |
| --- | --- |
| `taskstation self-host init` | Create or refresh the self-host config. Does not start the stack. |
| `taskstation self-host configure` | Interactive wizard for connections and update policy. |
| `taskstation self-host doctor` | Validate Docker tooling and the rendered config. |
| `taskstation self-host plan` | Validate the rendered Compose config; change nothing. |
| `taskstation self-host start` | Create config if needed, then start the stack. Aliases: `up`, `deploy`. |
| `taskstation self-host update [--tag <v>\|--channel stable\|latest]` | Pull images for the configured channel or tag and recreate the stack. Alias: `upgrade`/`reconcile`. |
| `taskstation self-host rollback --release <v>` | Roll back to an explicit older version. |
| `taskstation self-host version` | Show the running version and channel. |
| `taskstation self-host restart` / `stop` | Restart or stop the stack. Alias for stop: `down`. |
| `taskstation self-host status` / `ps` | Show service status. |
| `taskstation self-host open` | Open the dashboard in your browser. |
| `taskstation self-host connect-github` | Connect a GitHub App for managed repos. |
| `taskstation self-host env ls [--show]` | Show persistent config values, masking secrets by default. |
| `taskstation self-host env set KEY=VALUE ...` | Set a value and restart only the services it affects. |
| `taskstation self-host env rotate KEY\|--all-generated` | Regenerate a rotatable, CLI-generated secret. |
| `taskstation self-host logs [service]` | Tail stack logs. |
| `taskstation self-host uninstall` | Stop the stack and delete this instance's containers, volumes, and config. |

Common flags: `--instance <name>` (default `default`), `--domain <domain>`, `--tunnel cloudflare`, `--version`/`--tag`/`--release <v>`, `--channel stable|latest` (default `stable`), `--auto-update on|off` (default `on`; forced off by `--local-images`), `--update-time <HH:MM>` / `--update-tz <tz>` (auto-updater schedule), `--local-images` (run locally-built images; dev mode), `--enterprise-license` (unlock SSO/SCIM/RBAC/audit), `--admin-email <email>`, `--no-restrict-account-creation` (let any signed-in user create new accounts/orgs; default is admin-only), `--restrict-account-creation` (re-enable the admin-only default), `--json`, `--yes`.

### Token scope

Every token starts with `taskstation_pat_`. A user token is scoped to every project on your accounts. A project token is scoped to one project and auto-injected into that project's sandboxes. See the full token-family reference at [Session runtime](/docs/work/runtime).

### Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success. |
| `1` | Operation failed. Diagnostics print to stderr. |
| `2` | Bad flag, unknown subcommand, or missing required argument. |