---
title: Commands Reference
description: All CLI commands with syntax, options, and examples. Deploy side (login/init/plan/deploy/bootstrap/destroy/doctor/status/outputs/config) and API side (login --stage, me, logout, user, mcp, tools, thread, agent, inbox, routine, …).
---

import { Aside } from "@astrojs/starlight/components";

All commands follow the pattern:

```bash
thinkwork <command> [subcommand] [options]
```

The CLI has two command surfaces:

- **Deploy side** — `login`, `init`, `plan`, `deploy`, `bootstrap`, `destroy`, `doctor`, `status`, `outputs`, `config`. Shells out to `terraform` and `aws`. Needs AWS credentials.
- **API side** — `login --stage`, `me`, `logout`, `user`, `member`, `thread`, `agent`, `inbox`, `routine`, and everything else in the roadmap. Talks to the deployed GraphQL + REST APIs. Needs a Cognito or api-key session.
- **Enterprise deployment repo side** — `enterprise bootstrap` and `enterprise overlay`. Used once to create a customer-owned deployment repo, then by CI to apply customer overlays after deploy.

Run `thinkwork <any-command> --help` for the definitive, up-to-date flags and examples — every command ships interactive + scripted examples inline.

---

## Global options

These are accepted on **every** command:

| Flag                   | Description                                                           |
| ---------------------- | --------------------------------------------------------------------- |
| `-p, --profile <name>` | AWS profile (overrides `$AWS_PROFILE` and the CLI's `defaultProfile`) |
| `--json`               | Emit machine-readable JSON on stdout. Logs/spinners stay on stderr.   |
| `-h, --help`           | Print help for the current command                                    |
| `-v, --version`        | Print CLI version (program-level only)                                |

API-backed commands additionally accept:

| Flag                  | Description                                                                       |
| --------------------- | --------------------------------------------------------------------------------- |
| `-s, --stage <name>`  | Stage to target. Falls back to `$THINKWORK_STAGE`, then the saved `defaultStage`. |
| `-t, --tenant <slug>` | Tenant slug. Falls back to `$THINKWORK_TENANT`, then the cached session tenant.   |
| `-y, --yes`           | Skip confirmation on destructive verbs.                                           |

---

## login

Two modes, selected by `--stage`.

```bash
thinkwork login [options]
thinkwork login --stage <s> [options]
```

**Without `--stage`** — configure AWS credentials (arrow-key picker over `~/.aws/` profiles, with fall-through to access-key entry or `aws sso login`):

| Flag               | Description                                         |
| ------------------ | --------------------------------------------------- |
| `--profile <name>` | AWS profile to create/update (default: `thinkwork`) |
| `--sso`            | Skip the picker and run `aws sso login`             |
| `--keys`           | Skip the picker and prompt for fresh access keys    |

**With `--stage <s>`** — sign in to the deployed Cognito user pool:

| Flag                    | Description                                                                                        |
| ----------------------- | -------------------------------------------------------------------------------------------------- |
| `-s, --stage <name>`    | Deployed stage to sign in to                                                                       |
| `-r, --region <region>` | AWS region for the stack (default: `us-east-1`)                                                    |
| `--api-key <secret>`    | Non-interactive; skip the browser and store the api_auth_secret as the session                     |
| `--tenant <slug>`       | Cache this tenant slug on the session (with `--api-key`, or to override `bootstrapUser`'s default) |
| `--port <number>`       | Override the Cognito OAuth loopback port (default: 42010)                                          |
| `--no-browser`          | Print the authorize URL instead of opening a browser (useful over SSH)                             |

**Examples:**

```bash
# AWS profile picker (before deploy/destroy/list)
thinkwork login

# Skip picker, enter fresh keys
thinkwork login --keys --profile thinkwork

# AWS SSO
thinkwork login --sso --profile work-sso

# Cognito OAuth (opens browser, supports Google sign-in)
thinkwork login --stage dev

# Cognito over SSH — print URL, paste into a local browser
thinkwork login --stage dev --no-browser

# Non-interactive CI login with the api_auth_secret
thinkwork login --stage prod --api-key "$THINKWORK_API_KEY" --tenant acme
```

---

## logout

Forget stored stack sessions. Touches only `~/.thinkwork/config.json`; your AWS profile and Cognito pool are untouched.

```bash
thinkwork logout [options]
```

| Flag                 | Description                   |
| -------------------- | ----------------------------- |
| `-s, --stage <name>` | Stage whose session to forget |
| `--all`              | Forget every stage's session  |

**Examples:**

```bash
thinkwork logout --stage dev       # one stage
thinkwork logout --all             # every stage
thinkwork logout                   # interactive picker
```

---

## me

Print the identity behind the current session. Verifies the session works by round-tripping a live `me` GraphQL query.

```bash
thinkwork me [options]
```

| Flag                    | Description                       |
| ----------------------- | --------------------------------- |
| `-s, --stage <name>`    | Stage to introspect               |
| `-r, --region <region>` | AWS region (default: `us-east-1`) |

**Examples:**

```bash
thinkwork me                                       # default stage
thinkwork me --stage prod
thinkwork me --stage dev --json | jq .tenantSlug   # scriptable
```

---

## init

Scaffold a new ThinkWork deployment directory.

```bash
thinkwork init -s <stage> [options]
```

| Flag                 | Description                                |
| -------------------- | ------------------------------------------ |
| `-s, --stage <name>` | Stage name (required)                      |
| `-d, --dir <path>`   | Target directory (default: `.`)            |
| `--defaults`         | Skip interactive prompts, use all defaults |

**Example:**

```bash
mkdir my-deploy && cd my-deploy
thinkwork init -s dev
```

Creates `terraform.tfvars` + terraform module scaffolding + `~/.thinkwork/environments/<stage>/config.json`. See the [CLI Overview](/applications/cli/) for the registry layout.

---

## plan

Preview Terraform changes.

```bash
thinkwork plan -s <stage> [options]
```

| Flag                     | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| `-s, --stage <name>`     | Stage name (required)                                  |
| `-c, --component <tier>` | `foundation`, `data`, `app`, or `all` (default: `all`) |
| `-p, --profile <name>`   | AWS profile override                                   |

**Example:**

```bash
thinkwork plan -s dev
thinkwork plan -s dev -c app     # only the app tier
```

---

## deploy

Apply the Terraform plan.

```bash
thinkwork deploy -s <stage> [options]
```

| Flag                     | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| `-s, --stage <name>`     | Stage name (required)                                  |
| `-c, --component <tier>` | `foundation`, `data`, `app`, or `all` (default: `all`) |
| `-y, --yes`              | Skip confirmation (CI)                                 |
| `-p, --profile <name>`   | AWS profile override                                   |

**Examples:**

```bash
thinkwork deploy -s dev
thinkwork deploy -s prod --yes
thinkwork deploy -s dev -c app
```

<Aside type="caution">
  `--yes` bypasses the confirmation prompt. Do not use in scripts that run
  against production without a manual approval gate.
</Aside>

---

## bootstrap

Seed workspace defaults, the skill catalog, and per-tenant files for a deployed stack.

```bash
thinkwork bootstrap -s <stage>
```

| Flag                 | Description           |
| -------------------- | --------------------- |
| `-s, --stage <name>` | Stage name (required) |

Idempotent — safe to re-run after every deploy.

---

## enterprise

Commands for the recommended enterprise deployment repository path. See
[Enterprise Deployment Repo](/deploy/enterprise-deployment-repo/) for the full
operator guide.

### enterprise bootstrap

Render a customer deployment repository and configure the one-time AWS/GitHub
bootstrap resources needed for CI deploys.

```bash
thinkwork enterprise bootstrap [targetDir] [options]
```

| Flag                    | Description                                                 |
| ----------------------- | ----------------------------------------------------------- |
| `--customer <slug>`     | Customer slug used for repo defaults and tenant slugs       |
| `--repo <owner/name>`   | Customer GitHub deployment repository                       |
| `--stage <name>`        | Stage to include. Repeat for multiple stages                |
| `--region <region>`     | AWS region                                                  |
| `--release-version <v>` | ThinkWork release pin                                       |
| `--dry-run`             | Validate and print planned work without mutating AWS/GitHub |

Example:

```bash
thinkwork enterprise bootstrap ./acme-thinkwork-deploy \
  --customer acme \
  --repo acme-corp/acme-thinkwork-deploy \
  --stage dev \
  --stage prod \
  --region us-east-1
```

### enterprise overlay

Validate or apply the customer overlay contract from a deployment repo.

```bash
thinkwork enterprise overlay plan [repoRoot] --stage <stage> --json
thinkwork enterprise overlay apply [repoRoot] --stage <stage> --tenant <slug> --json
```

| Flag                    | Description                                        |
| ----------------------- | -------------------------------------------------- |
| `-s, --stage <name>`    | Stage from `customer/deployment.json`              |
| `-t, --tenant <slug>`   | Tenant slug to target during apply                 |
| `-r, --region <region>` | AWS region                                         |
| `--dry-run`             | Validate and print the apply plan without mutation |

CI uses `enterprise overlay apply` after Terraform deploy. A local dry-run is
safe because it validates the repo contract before any API or AWS mutation.

---

## doctor

Check AWS account prerequisites for a Thinkwork deployment (Bedrock access, IAM, etc.).

```bash
thinkwork doctor -s <stage>
```

| Flag                   | Description           |
| ---------------------- | --------------------- |
| `-s, --stage <name>`   | Stage name (required) |
| `-p, --profile <name>` | AWS profile override  |

---

## destroy

Tear down a stage. Inside a generated enterprise deployment repo, or when
`--customer`/`--repo` is provided, this dispatches the customer-owned CI
workflow with `operation=destroy`. Outside enterprise context it runs local
Terraform destroy.

```bash
thinkwork destroy -s <stage> [options]
```

| Flag                     | Description                                                 |
| ------------------------ | ----------------------------------------------------------- |
| `-s, --stage <name>`     | Stage name. Prompts in enterprise TTY flows when omitted.   |
| `-c, --component <tier>` | Local Terraform only: `foundation`, `data`, `app`, or `all` |
| `--customer <slug>`      | Enterprise customer slug                                    |
| `--repo <owner/name>`    | Enterprise deployment repository                            |
| `--wait`, `--no-wait`    | Wait or return after enterprise workflow dispatch           |
| `--local-terraform`      | Force local Terraform destroy inside a deployment repo      |
| `-y, --yes`              | Skip confirmation                                           |

<Aside type="caution">
  `destroy` deletes your Aurora database, all S3 data, and all application
  infrastructure. Aurora deletion protection is enabled by default — if
  `protect_aurora = true`, you must disable it in the AWS console before
  `destroy` will proceed.
</Aside>

---

## status

Discover all deployed environments and their health.

```bash
thinkwork status [-s <stage>]
```

Without `-s`, prints a table of every deployed stage across the account.

With `-s`, prints the detailed view for one stage — Lambda counts, AgentCore, memory backends, etc.

Aliases: `list`, `ls`.

---

## outputs

Print Terraform outputs for a deployed stage.

```bash
thinkwork outputs -s <stage> [options]
```

| Flag                     | Description                        |
| ------------------------ | ---------------------------------- |
| `-s, --stage <name>`     | Stage name (required)              |
| `-c, --component <tier>` | Tier to read from (default: `all`) |

Use `--json` to pipe the outputs to jq / terraform / other tools.

---

## config

View or edit CLI configuration for a stage.

```bash
thinkwork config <subcommand> [options]
```

### config list

```bash
thinkwork config list [-s <stage>]
```

Without `-s`: table of all initialized environments.
With `-s`: full config for that environment (secrets masked).

### config get

```bash
thinkwork config get <key> -s <stage>
```

### config set

```bash
thinkwork config set <key> <value> -s <stage>
```

Updates `terraform.tfvars`. Run `thinkwork deploy -s <stage>` to apply.

---

## user

User-management utilities for a deployed stack.

### user invite

```bash
thinkwork user invite [email] [options]
```

Creates the Cognito user (Cognito emails a temporary password) and adds them as a tenant member. Prompts interactively for any missing fields.

| Flag                 | Description                             |
| -------------------- | --------------------------------------- |
| `-s, --stage <name>` | Deployment stage                        |
| `--tenant <slug>`    | Tenant slug                             |
| `--name <name>`      | Display name                            |
| `--role <role>`      | `member` (default), `admin`, or `owner` |
| `--region <region>`  | AWS region (default: `us-east-1`)       |

**Examples:**

```bash
# Fully interactive
thinkwork user invite

# Scripted
thinkwork user invite alice@example.com --tenant acme -s dev --role admin

# Mix
thinkwork user invite alice@example.com
```

### user reset-password

```bash
thinkwork user reset-password <email> -s <stage>
```

Triggers Cognito's admin-initiated forgot-password flow — useful when a user is locked out or in `FORCE_CHANGE_PASSWORD`.

---

## mcp

Manage MCP servers (Model Context Protocol) for a tenant.

### mcp list / add / remove / test / assign / unassign

```bash
thinkwork mcp list --tenant <slug> -s <stage>
thinkwork mcp add <name> --url <url> --tenant <slug> -s <stage> [options]
thinkwork mcp remove <server-id> --tenant <slug> -s <stage>
thinkwork mcp test <server-id> --tenant <slug> -s <stage>
thinkwork mcp assign <server-id> --agent <agent-id> -s <stage>
thinkwork mcp unassign <server-id> --agent <agent-id> -s <stage>
```

Run `thinkwork mcp <sub> --help` for the full options list on each subcommand, including `--auth-type` (`none` | `tenant_api_key` | `oauth`) and `--transport` (`streamable-http` | `sse`).

### mcp key create / list / revoke

Per-tenant Bearer tokens for the admin-ops MCP server (served at `mcp.thinkwork.ai/mcp/admin`). Each token is scoped to one tenant; callers present it as `Authorization: Bearer tkm_…` against the admin-ops HTTP endpoint.

```bash
# Mint a new tkm_ token (printed ONCE — save it immediately)
thinkwork mcp key create -t <tenant-slug> [--name <label>] -s <stage>

# List existing keys for a tenant (metadata only; raw tokens never returned)
thinkwork mcp key list -t <tenant-slug> [--all] -s <stage>   # --all includes revoked rows

# Revoke a key by id (idempotent)
thinkwork mcp key revoke <key-id> -t <tenant-slug> -s <stage>
```

Server-side the token is stored as a SHA-256 hash in `tenant_mcp_admin_keys`; the raw value lives only in Secrets Manager at `/thinkwork/<stage>/mcp/<tenantId>/<server-slug>`. Rotate by creating a new key + revoking the old one.

### mcp provision

One-shot idempotent provisioning of the admin-ops MCP for a tenant: mints a fresh `tkm_` token, stores it in Secrets Manager, and upserts the matching `tenant_mcp_servers` row so agents can subscribe.

```bash
# Single tenant (interactive picker or -t)
thinkwork mcp provision -t <slug> [--url https://mcp.thinkwork.ai/mcp/admin] -s <stage>

# Backfill every tenant at once
thinkwork mcp provision --all -s <stage>
```

The raw token is **not** printed by `provision` — it only lives in Secrets Manager + the `tenant_mcp_servers.auth_config` row. Re-running `provision` rotates the "default" key and retires the previous one. After provisioning, each agent still needs the server assigned via `thinkwork mcp assign` (or the admin SPA's MCP Servers tab).

The admin SPA's Agent Templates → MCP Servers tab also exposes a **Generate and save a new key** button for `tenant_api_key` servers that calls the same provision path — admins don't need the CLI for the common case.

---

## tools

Manage credentialed tenant built-in tool configuration. Today this command manages Web Search provider keys; policy/template-gated built-ins such as Code Sandbox, Browser Automation, and Send Email are configured in the admin app.

```bash
thinkwork tools list
thinkwork tools web-search set|test|disable|clear
```

Run `thinkwork tools --help` for the full subcommand tree.

Use [Admin → Built-in Tools](/applications/admin/builtin-tools/) to inspect the full built-in catalog, and [Admin → Agent Templates](/applications/admin/agent-templates/) to opt templates into `execute_code`, `browser_automation`, `web_search`, and `send_email`.

---

## update

Upgrade the CLI's bundled Terraform modules to match the installed CLI version.

```bash
thinkwork update -s <stage>
```

---

## wiki

**Admin-only.** Operator controls for the Compounding Memory (wiki) compile
pipeline. Enqueue compiles, rebuild from scratch, and inspect recent job
activity from a terminal.

The underlying GraphQL mutations assert api-key or admin-promoted tenant
membership — Cognito end-user sessions get a clear "admin access required"
hint and exit code 2.

### wiki compile

Enqueue a compile for one agent or fan out across every tenant agent.

```bash
thinkwork wiki compile [-t <tenant>] [--agent <id>] [--all] [--model <id>] [--watch] [--json]
```

- `--agent <id|slug|name>` — single-agent mode. Bypasses the picker.
- `--all` — fan out to every non-system agent in the tenant. One enqueue per agent; dedupe is handled server-side.
- `--model <id>` — Bedrock model override for this run only (e.g.
  `anthropic.claude-sonnet-4-6-v1:0`). Defaults to the server's
  `BEDROCK_MODEL_ID`. The override travels via the Lambda Event payload;
  if the invoke fails and a polling worker later claims the job, the
  env-default model is used.
- `--watch` — after enqueue, poll `wiki_compile_jobs` until the job reaches a
  terminal state. Single-agent only; ignored with `--all`.

### wiki rebuild

**Destructive.** Archive the agent's active wiki pages, clear the compile
cursor, then enqueue a fresh compile. Single-agent only — `--all` is
rejected to avoid accidental tenant-wide rebuilds.

```bash
thinkwork wiki rebuild -t <tenant> --agent <id> [--model <id>] [--yes] [--watch] [--json]
```

- Prompts for confirmation unless `--yes` or `--json`.
- If the reset succeeds but the compile enqueue fails, the command exits 1
  with the exact retry command (`thinkwork wiki compile --agent <id>`) so
  you don't need to re-run the destructive step.

### wiki status

Show recent compile jobs for a tenant, optionally filtered to a single agent.

```bash
thinkwork wiki status [-t <tenant>] [--agent <id>] [-n <limit>] [--watch] [--timeout <sec>] [--json]
```

- Omit `--agent` for tenant-wide recent activity (useful for spotting
  stalled or repeatedly-failing agents).
- `--watch` polls the most-recent job until it reaches a terminal state,
  with a 15-minute default timeout (`--timeout`).

---

## thread

Threads are tenant-scoped work items (tasks, conversations, bug reports, questions). The `thread` command lets you list, create, update, comment on, and route threads from the terminal — the same operations the admin UI exposes.

```bash
thinkwork thread <subcommand> [args] [options]
```

All subcommands accept `-s/--stage`, `-t/--tenant`, and the global `--json`.

### thread list

```bash
thinkwork thread list [--assignee <id|me>] [--agent <id>] [--search <q>] [--limit <n>] [--archived]
```

- `--assignee me` resolves to the caller's Cognito principal. Requires a Cognito session.
- Archived threads are filtered out by default — pass `--archived` to include them.
- `--limit` defaults to 50.

### thread get

```bash
thinkwork thread get <idOrNumber>
```

Accepts either a thread ID (e.g. `thr-abc123` or a UUID) or a tenant-scoped issue number (e.g. `42`). Numeric input dispatches `threadByNumber`; anything else dispatches `thread(id:)`.

### thread create

```bash
thinkwork thread create [title] [--assignee <id>] [--due <iso>] [--label <name>...]
```

In a TTY with no arguments, prompts for title and assignee. `--label` accepts a repeatable list of label _names_ (not IDs); names are resolved against `threadLabels(tenantId:)` before the create and attached via `assignThreadLabel` after.

### thread update

```bash
thinkwork thread update <id> [--title <t>] [--assignee <id>] [--due <iso>]
```

Only flags you pass are sent in `UpdateThreadInput`. Requires at least one of `--title`, `--assignee`, `--due`.

### thread checkout / release

```bash
thinkwork thread checkout <id>
thinkwork thread release <id> --run-id <id>
```

`checkout` generates a fresh `cli-<uuid>` runId, locks the thread under it, and prints the runId. Pair it with `release --run-id <id>` to release the lock. The `--agent` flag on `checkout` is informational only — checkout is tracked by the runId, not by an agent identity.

### thread comment

```bash
thinkwork thread comment <id> [content] [--file <path>]
```

Posts a `USER` message to the thread. The schema has no separate operator-comment surface; comments and conversational messages share the same `Message` list and are distinguished by `senderType`.

### thread label

```bash
thinkwork thread label assign <threadId> <labelId>
thinkwork thread label remove <threadId> <labelId>
```

Attach or detach an existing label on a thread. Manage label CRUD (create / update / delete labels themselves) with `thinkwork label`.

### thread escalate / delegate

```bash
thinkwork thread escalate <id> --to-agent <id> --reason <text>
thinkwork thread delegate <id> --to-agent <id> [--reason <text>]
```

`escalate` requires a `--reason` (it lands in the activity log). `delegate` requires a Cognito session so the API can record who delegated.

### thread delete

```bash
thinkwork thread delete <id> [--yes]
```

Hard-deletes the thread (not just closes it). Prompts for confirmation in a TTY; refuses in a non-interactive session without `--yes`.

---

## message

Send messages to threads and list a thread's message history. Messages share the same surface as `thread comment` — both create `Message` rows on a thread, distinguished by `role` and `senderType`.

```bash
thinkwork message <subcommand> [args] [options]
```

All subcommands accept `-s/--stage`, `-t/--tenant`, and the global `--json`. Aliases: `messages`, `msg`.

### message send

```bash
thinkwork message send <threadId> [content] [--file <path>] [--as-agent <id>]
```

- Content comes from the positional arg, `--file <path>`, or an interactive prompt (TTY only).
- Default role is `USER`. With `--as-agent <id>`, role becomes `ASSISTANT`, `senderType` becomes `agent`, and `senderId` becomes the supplied agent ID.
- `--as-agent` requires an api-key session — the API enforces that only an agent's own bearer can post as that agent. Cognito sessions error with a clear message.

### message list

```bash
thinkwork message list <threadId> [--limit <n>] [--cursor <c>]
```

- Paginated via cursor. `--limit` defaults to 50. The next-page cursor is printed below the table when more results exist.
- JSON mode (`--json`) emits `{ messages, pageInfo }` directly for scripting.

---

## label

Manage tenant-wide thread labels (Gmail-style tags applied to threads).

```bash
thinkwork label <subcommand> [args] [options]
```

All subcommands accept `-s/--stage`, `-t/--tenant`, and the global `--json`. Alias: `labels`.

To attach or detach a label on a specific thread, use `thinkwork thread label assign|remove`. The `label` command only manages label CRUD; assignments live on threads.

### label list

```bash
thinkwork label list
```

Prints id / name / color / description for every label in the tenant.

### label create

```bash
thinkwork label create [name] [--color <hex>] [--description <text>]
```

- In a TTY with no name, prompts for name and color.
- `--color` validates against `^#[0-9a-fA-F]{6}$`; invalid formats error before the API call.

### label update

```bash
thinkwork label update <id> [--name <n>] [--color <hex>] [--description <text>]
```

Only flags you pass are sent in `UpdateThreadLabelInput`. Requires at least one of `--name`, `--color`, `--description`.

### label delete

```bash
thinkwork label delete <id> [--yes]
```

Deletes the label. Any existing thread-label assignments are removed automatically. Prompts for confirmation in a TTY; refuses in a non-interactive session without `--yes`.

---

## inbox

Approval flows for agent-proposed changes — list, view, approve/reject, request revisions, resubmit, cancel, comment.

```bash
thinkwork inbox <subcommand> [args] [options]
```

All subcommands accept `-s/--stage`, `-t/--tenant`, and the global `--json`.

### inbox list

```bash
thinkwork inbox list [--status <s>] [--entity-type <t>] [--entity-id <id>] [--mine]
```

- `--status` defaults to `PENDING`. Accepts `PENDING | APPROVED | REJECTED | REVISION_REQUESTED | EXPIRED | CANCELLED`.
- `--mine` filters to items routed to the caller; requires a Cognito session (api-key sessions error with guidance).
- `--entity-type` + `--entity-id` filter by what the inbox item targets (e.g. a specific thread).

### inbox get

```bash
thinkwork inbox get <id>
```

Prints the full inbox item: metadata, attached comments, links, and any linked threads.

### inbox approve / reject

```bash
thinkwork inbox approve <id> [--notes <text>]
thinkwork inbox reject <id>  [--notes <text>]
```

`--notes` becomes `reviewNotes` on the decision. For inbox items whose recipe declared a structured `decisionSchema`, the CLI currently does not provide a way to supply matching values — use the admin UI for those.

### inbox request-revision

```bash
thinkwork inbox request-revision <id> --notes <text>
```

`--notes` is **required** (the API mandates a non-null reason). In a TTY without `--notes`, prompts; non-TTY without `--notes` errors.

### inbox resubmit

```bash
thinkwork inbox resubmit <id> [--notes <text>]
```

If `--notes` is provided, it lands in the resubmit's `description` field. The CLI does not currently surface `--title` or `--config` overrides — use the admin UI for richer payloads.

### inbox cancel

```bash
thinkwork inbox cancel <id>
```

Cancels a pending item. Calling on an already-CANCELLED item surfaces the API error.

### inbox comment

```bash
thinkwork inbox comment <id> [content] [--file <path>]
```

Adds a comment to the inbox item without deciding on it. Content from positional arg, `--file`, or interactive prompt. `authorType`/`authorId` are filled from the session when Cognito-authenticated.

---

## member

List and manage tenant members (users + agents with access to a tenant). Calls the same `inviteMember` / `updateTenantMember` / `removeTenantMember` mutations the admin UI uses.

```bash
thinkwork member <subcommand> [args] [options]
```

All subcommands accept `-s/--stage`, `-t/--tenant`, and the global `--json`. Alias: `members`.

### member list

```bash
thinkwork member list [--principal-type USER|AGENT] [--role <r>]
```

- Returns id / type / principal / role / status for every member.
- Both filters are client-side post-query (the server returns the full list).

### member invite

```bash
thinkwork member invite [email] [--role member|admin|owner] [--name <n>]
```

- TTY without email → prompts.
- `--role` defaults to `member`.
- Sends an invite email and creates the Cognito user via the existing `inviteMember` resolver.

### member update

```bash
thinkwork member update <memberId> [--role <r>] [--status active|suspended]
```

Only flags you pass become part of the update input. Requires at least one of `--role`, `--status`.

### member remove

```bash
thinkwork member remove <memberId> [--yes]
```

Removes the membership. The underlying Cognito user is **not** deleted. Prompts for confirmation in a TTY; refuses in non-interactive sessions without `--yes`.

---

## team

Teams are workspace subdivisions inside a tenant. Each has a name, optional sub-budget, and roster of agent + user members. Use teams to scope budgets and route work to a subset of agents.

```bash
thinkwork team <subcommand> [args] [options]
```

All subcommands accept `-s/--stage`, `-t/--tenant`, and the global `--json`. Alias: `teams`.

### team list / get

```bash
thinkwork team list
thinkwork team get <id>
```

`list` is a tenant-wide table (id / name / type / status / budget). `get` shows team metadata plus the agent + user rosters.

### team create / update / delete

```bash
thinkwork team create [name] [--description <t>] [--budget-usd <n>]
thinkwork team update <id> [--name <n>] [--description <t>] [--status active|archived] [--budget-usd <n>]
thinkwork team delete <id> [--yes]
```

- `create` prompts for `name` in a TTY when omitted; `--budget-usd` is optional (stored as `budgetMonthlyCents` after × 100).
- `update` accepts partial input; requires at least one of the four flags.
- `delete` honors `-y/--yes` (archives the team rather than hard-deleting).

### team add-agent / remove-agent

```bash
thinkwork team add-agent    <teamId> <agentId>
thinkwork team remove-agent <teamId> <agentId>
```

Manage the team's agent roster. Both verbs are idempotent at the API level (re-adding or re-removing returns the current state, doesn't error).

### team add-user / remove-user

```bash
thinkwork team add-user    <teamId> <userId>
thinkwork team remove-user <teamId> <userId>
```

Manage the team's user roster. Same idempotency semantics as the agent verbs.

---

## kb

Knowledge bases (Bedrock-backed RAG stores) and the agent-attachment side. Each KB has an embedding model, chunking config, and a sync lifecycle; attached KBs are queried by agents at run-time for grounded retrieval.

```bash
thinkwork kb <subcommand> [args] [options]
```

All subcommands accept `-s/--stage`, `-t/--tenant`, and the global `--json`. Alias: `knowledge-base`.

### kb list / get

```bash
thinkwork kb list
thinkwork kb get <id>
```

`list` is a tenant table with status + sync indicators. `get` returns the full KB record (embedding model, chunking, sync history, error message).

### kb create / update / delete

```bash
thinkwork kb create [name] [--s3-uri <uri>] [--description <t>] [--embedding-model <id>]
thinkwork kb update <id> [--name <n>] [--description <t>]
thinkwork kb delete <id> [--yes]
```

- `create` prompts for `name` in a TTY when omitted.
- `--s3-uri` is currently a no-op flag — set the source in the admin UI after create. The flag is reserved for forward compatibility.
- `--embedding-model` accepts any Bedrock embedding model ID; defaults are tenant-level.
- `update` only changes metadata; source changes still require re-create.
- `delete` honors `-y/--yes`; the prompt warns that embeddings + index will be destroyed.

### kb sync

```bash
thinkwork kb sync <id> [--wait]
```

Re-embeds from the configured source. Idempotent. `--wait` is currently a no-op; poll `kb get` until `lastSyncStatus` is terminal.

### kb attach / detach

```bash
thinkwork kb attach <kbId> --agent <id> [--config <json>]
thinkwork kb detach <kbId> --agent <id>
```

Both verbs use the bulk `setAgentKnowledgeBases` mutation under the hood as a read-modify-write — the CLI reads the agent's current attachments, adds or removes this KB, and replaces the full set. `--config <json>` parses as `searchConfig` (e.g. `{"topK":5,"scoreThreshold":0.7}`).

---

## template

Agent templates — reusable configs you spawn agents from. Use templates to bake in model, prompt files, default capabilities, skills, knowledge bases, and sandbox/browser/web-search opt-in. Linked agents do **not** auto-sync when a template changes — use `template sync-agent` / `template sync-all` deliberately.

```bash
thinkwork template <subcommand> [args] [options]
```

All subcommands accept `-s/--stage`, `-t/--tenant`, and the global `--json`. Alias: `templates`.

### template list / get

```bash
thinkwork template list
thinkwork template get <id>
```

`list` shows id / name / slug / runtime / kind / model / published. `get` returns the full template record.

### template create / update / delete

```bash
thinkwork template create [name] [--from-agent <id>] [--model <m>] [--description <t>] [--system-prompt-file <path>]
thinkwork template update <id> [--name <n>] [--model <m>] [--description <t>] [--system-prompt-file <path>]
thinkwork template delete <id> [--yes]
```

- `--from-agent <id>` clones name + role + linked-template model from an existing agent. The CLI composes the `CreateAgentTemplateInput` client-side; the template's deep config (skills, knowledge bases, workspace files) is not cloned — edit those in the admin UI after create if needed.
- `--system-prompt-file` is currently a no-op flag with a warning. Template prompt content lives in linked workspace files; edit them via the admin UI.
- `update` is partial — only flags passed are sent in `UpdateAgentTemplateInput`.
- `delete` honors `-y/--yes`. Linked agents are unaffected; they just stop being in sync.

### template diff

```bash
thinkwork template diff <templateId> <agentId>
```

Side-by-side compare on the top-level fields the CLI tracks (name, description / role, runtime, model). Deeper config (skills / KB / workspace files) is not compared at the CLI level — use the admin UI for a full diff.

### template sync-agent / sync-all

```bash
thinkwork template sync-agent <templateId> <agentId> [--yes]
thinkwork template sync-all   <templateId>           [--yes]
```

Both invoke their respective mutations server-side (`syncTemplateToAgent` / `syncTemplateToAllAgents`). Both prompt for confirmation in a TTY unless `-y/--yes` is passed. `sync-all` reports `agentsSynced` / `agentsFailed` plus any per-agent error strings.

---

## tenant

Tenant (workspace) lifecycle — create, rename, configure plan and per-tenant settings (default model, monthly budget, agent cap, auto-close, feature flags).

```bash
thinkwork tenant <subcommand> [args] [options]
```

All subcommands accept `-s/--stage` and the global `--json`. Alias: `tenants`. **Note:** `list` and `get` use the `@thinkwork/admin-ops` REST client; `create`, `update`, and `settings get`/`set` use GraphQL via the standard CLI client. Mixed substrate is intentional pending admin-ops parity.

### tenant list / get

```bash
thinkwork tenant list
thinkwork tenant get <idOrSlug>
```

`list` returns every tenant the caller can see (REST). `get` accepts either a UUID or slug.

### tenant create / update

```bash
thinkwork tenant create [name] [--slug <slug>] [--plan <plan>] [--issue-prefix <prefix>]
thinkwork tenant update <id> [--name <n>] [--plan <plan>] [--issue-prefix <prefix>]
```

- `create` prompts for `name` in a TTY when omitted. `--slug` is generated from name when absent (lowercased, hyphenated, ≤48 chars).
- `--plan` defaults to `team` on create.
- `--issue-prefix` is the tenant-scoped thread-number prefix (e.g. `ACME`). On create, it's applied via a follow-up `updateTenant` since the create input doesn't accept it.
- `update` is partial — only flags passed are sent.

### tenant settings get / set

```bash
thinkwork tenant settings get [tenant]
thinkwork tenant settings set [tenant] [--default-model <id>] [--monthly-budget-usd <n>] [--max-agents <n>] [--auto-close-after-days <n>] [--feature <key=value>...]
```

- `[tenant]` is optional; defaults to the session's tenant. Pass a slug to target a different tenant.
- `--monthly-budget-usd` converts to `budgetMonthlyCents` (× 100).
- `--auto-close-after-days` converts to `autoCloseThreadMinutes` (× 60 × 24).
- `--feature key=value` is repeatable. Values are auto-parsed: `true`/`false` → bool, integers → number, otherwise string. Example: `--feature hindsight=true --feature beta_tool=false`.

---

## agent

Agent lifecycle + capabilities, skills, budgets, API keys, email channels, and version history. Largest command group of Phase 2. Implementations live under `apps/cli/src/commands/agent/`.

```bash
thinkwork agent <subcommand> [args] [options]
```

All subcommands accept `-s/--stage`, `-t/--tenant`, and the global `--json`. Alias: `agents`.

### agent list / get

```bash
thinkwork agent list [--status IDLE|BUSY|OFFLINE|ERROR] [--type AGENT|GATEWAY|SUPERVISOR] [--include-system] [--all]
thinkwork agent get <id>
```

`list` returns the caller's paired agents; `--all` switches to the admin-only `allTenantAgents` query (every agent in the tenant, requires owner/admin). `get` returns the agent with its capabilities, skills, and budget policy.

### agent create / update / delete

```bash
thinkwork agent create [name] --template <id> [--role <r>] [--type <t>] [--parent <id>] [--reports-to <id>] [--system-prompt <text>|--system-prompt-file <path>] [--model <id>]
thinkwork agent update <id> [same field flags as create]
thinkwork agent delete <id> [--yes]
```

- `--template` is **required** for create (`CreateAgentInput.templateId` is non-null). See `thinkwork template list` for IDs.
- `--type` accepts `AGENT | GATEWAY | SUPERVISOR` (the actual enum values — the scaffolded help text mentioning HUMAN_PAIR / TEAM_AGENT / SUB_AGENT was outdated).
- `--model` carries into `runtimeConfig.model` rather than a top-level field.
- `delete` archives (soft-delete) the agent; existing threads stay, no new work routed.

### agent status / unpause

```bash
thinkwork agent status <id> <IDLE|BUSY|OFFLINE|ERROR>
thinkwork agent unpause <id>     # convenience: set status IDLE
```

### agent capabilities set

```bash
thinkwork agent capabilities set <agentId> --capability <name> [--enabled|--disabled]
```

The API exposes `setAgentCapabilities` as a bulk-replace mutation, so the CLI reads the agent's current capability list, modifies in place (or inserts), and rewrites the full set. Same read-modify-write pattern as `kb attach/detach`.

### agent skills set

```bash
thinkwork agent skills set <agentId> --skill <id> [--enabled|--disabled] [--config <json>] [--rate-limit <rpm>]
```

Same bulk-replace shape as capabilities. `--config` parses as JSON; `--rate-limit` is requests/minute.

### agent budget set / clear

```bash
thinkwork agent budget set <agentId> --limit-usd <amount> [--window daily|weekly|monthly] [--action PAUSE|ALERT]
thinkwork agent budget clear <agentId>
```

- `--window` defaults to `monthly`, `--action` defaults to `PAUSE`.
- `clear` removes the per-agent policy; the agent falls back to the tenant-wide budget.

### agent api-key

```bash
thinkwork agent api-key list <agentId>
thinkwork agent api-key create <agentId> [--name <label>] [--expires <iso>]
thinkwork agent api-key revoke <keyId> [--yes]
```

- `create` returns `{ apiKey: {...metadata}, plainTextKey }`. **The plaintext secret prints once** — save it; the server doesn't store it.
- `--expires` is currently a no-op (the `AgentApiKey` row has no expiration field); the flag is accepted for forward compat.
- `revoke` honors `-y/--yes`.

### agent email

```bash
thinkwork agent email enable  <agentId> [--local-part <x>]
thinkwork agent email disable <agentId>
thinkwork agent email allowlist <agentId> <sender>...
```

- `enable` toggles the email channel on; with `--local-part`, also claims a vanity address (`<local-part>@<tenant-domain>`).
- `disable` releases the vanity address (idempotent if none was claimed) and toggles the channel off.
- `allowlist` replaces the full list of permitted sender addresses (positional varargs).

### agent version list / rollback

```bash
thinkwork agent version list <agentId> [--limit <n>]
thinkwork agent version rollback <agentId> <versionId> [--yes]
```

- `list` is paginated by `--limit` (default 20).
- `rollback` creates a _new_ version pointing at the old config (history is preserved). Honors `-y/--yes`.

---

## Command surface (all phases live)

All 25 originally-scaffolded commands across Phases 1–5 are real and shipped. `thinkwork <cmd> --help` is authoritative for flags + examples; the sections below are summaries.

| Phase                         | Commands                                                                                                                                                       |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 — Work & approvals          | [`thread`](#thread), [`message`](#message), [`label`](#label), [`inbox`](#inbox)                                                                               |
| 2 — Agents & workspace        | [`member`](#member), [`team`](#team), [`kb`](#kb), [`template`](#template), [`tenant`](#tenant), [`agent`](#agent)                                             |
| 3 — Automation & integrations | [`routine`](#routine), [`scheduled-job`](#scheduled-job), [`turn`](#turn), [`wakeup`](#wakeup), [`webhook`](#webhook), [`skill`](#skill) — `connector` retired |
| 4 — Memory & artifacts        | [`memory`](#memory), [`recipe`](#recipe), [`artifact`](#artifact)                                                                                              |
| 5 — Observability & spend     | [`cost`](#cost), [`budget`](#budget), [`performance`](#performance), [`trace`](#trace), [`dashboard`](#dashboard)                                              |

`skill create` and `skill update` were **retired** — custom-skill authoring is `thinkwork skill push <folder>`. Invoking the retired verbs prints the explanation and exits 2.

### routine

Saved workflows with triggers and run history.

```bash
thinkwork routine list | get <id> | create [name] [--agent|--team] [--config-file]
thinkwork routine update <id> | delete <id>
thinkwork routine trigger <id> [--wait] [--input <json>]
thinkwork routine run list <routineId> | get <runId>
thinkwork routine trigger-config set <routineId> --type CRON|WEBHOOK|EVENT [--schedule]
thinkwork routine trigger-config delete <triggerId>
```

### scheduled-job

AWS-Scheduler-backed recurring agent jobs. Alias: `cron`.

```bash
thinkwork scheduled-job list | get <id>
thinkwork scheduled-job create [name] [--agent|--routine] --schedule <cron|rate> [--timezone] [--payload]
thinkwork scheduled-job update <id> [--schedule] [--timezone] [--payload] [--enable|--disable] [--name] [--description] [--prompt]
thinkwork scheduled-job delete <id> [--yes]
thinkwork scheduled-job run <id>
```

- `update` propagates schedule changes to AWS EventBridge synchronously via the job-schedule-manager Lambda. The DB row is preserved on Lambda failure so a retry is safe.
- `delete` deprovisions the EventBridge schedule before removing the row. Confirmation prompt unless `--yes`.
- `run` fires the job-trigger Lambda immediately with the row's payload (synchronous RequestResponse); downstream side effects (thread turn, routine run) remain async.

### turn

Inspect and cancel in-flight agent invocations (thread turns).

```bash
thinkwork turn list [--agent] [--routine] [--thread] [--status] [--limit]
thinkwork turn get <id>
thinkwork turn cancel <id> [--yes]
```

### wakeup

Queued deferred agent invocations.

```bash
thinkwork wakeup list
thinkwork wakeup create --agent <id> [--thread] [--delay-seconds] [--payload <json>]
```

### webhook

Inbound webhooks that dispatch agents or routines.

```bash
thinkwork webhook list | get <id>
thinkwork webhook create [name] --target-type AGENT|ROUTINE --target-id <id> [--rate-limit]
thinkwork webhook update <id> | delete <id> | rotate <id>
thinkwork webhook test <id>
thinkwork webhook deliveries <id> [--limit]
```

- `test` records a synthetic delivery row (`resolution_status: "test"`) so you can confirm the webhook is wired without triggering downstream dispatch. The CLI prints a copy-pasteable curl one-liner for end-to-end reachability against the public URL.
- `deliveries` lists recent inbound requests for one webhook (newest first; default 50, max 500). Rows are PII-bearing (provider task titles, customer names in body previews) — the read is admin-tier.

### skill

Browse the catalog and install / upgrade / uninstall tenant-scoped skills. Custom-skill authoring is `thinkwork skill push <folder>` — that uploads a folder and registers it as a tenant-owned skill.

```bash
thinkwork skill catalog [--search] [--tag]
thinkwork skill list [--custom-only]
thinkwork skill install <slug> [--version]
thinkwork skill upgrade <slug> [--version]
thinkwork skill delete <slug> [--yes]
thinkwork skill push <folder>
```

- `install` and `upgrade` both call the same idempotent `installSkill` mutation — upsert into `tenant_skills`. When `--version` is omitted the resolver reads the catalog's current version; for slugs not in the catalog, `--version` is required.
- `delete` removes the `tenant_skills` row (does NOT cascade to agent assignments). Confirmation prompt unless `--yes`.
- `skill create` and `skill update` are **retired** — use `skill push` for authoring. Running them prints the explanation and exits 2.

### memory

Inspect, search, and edit an agent's managed memory (AgentCore / Hindsight) and memory graph.

```bash
thinkwork memory list --agent <id> [--namespace semantic|preferences|episodes|reflections]
thinkwork memory search --agent <id> --query <q> [--strategy] [--limit]
thinkwork memory get <recordId> | update <recordId> --content <text> | delete <recordId>
thinkwork memory graph --agent <id>
```

### recipe

Saved MCP tool invocations (parameterized one-click actions).

```bash
thinkwork recipe list [--thread] [--agent] | get <id>
thinkwork recipe create [name] --tool <slug> [--params <json>] [--scope tenant|agent|thread]
thinkwork recipe update <id> | delete <id>
```

### artifact

Agent-produced markdown outputs (reports, data-views, notes, plans, drafts, digests). Read-only in v1.

```bash
thinkwork artifact list [--thread] [--agent] [--type] [--status]
thinkwork artifact get <id> [--raw]
```

### cost

```bash
thinkwork cost summary [--from] [--to]
thinkwork cost by-agent [--sort cost|requests]
thinkwork cost by-model
thinkwork cost series [--days]
```

### budget

```bash
thinkwork budget list | status
thinkwork budget upsert --limit-usd <n> [--scope tenant|agent] [--agent] [--window] [--action PAUSE|ALERT]
thinkwork budget delete <id>
```

### performance

```bash
thinkwork performance agents [--from] [--to] [--sort cost|errors|latency|requests]
thinkwork performance agent <id> [--days]
```

### trace

```bash
thinkwork trace thread <threadId> [--since]
thinkwork trace turn <turnId> [--raw]
```

### dashboard

```bash
thinkwork dashboard
```

One-screen snapshot — agents online, open threads, pending approvals, spend-to-date.
