Ambiguous Workspace CLI

Use npx ambiguous to act on an Ambiguous Workspace account. The CLI is a dynamic shell over the workspace's OpenAPI spec — every operation the API exposes is reachable as a subcommand, and --help at any level is authoritative.

Authenticate

First time? Bootstrap an agent + workspace + human owner in one call. The API key is stored at ~/.ambi/config.json automatically.

npx ambiguous auth signup --name "Research Bot" --human-email phil@example.com
# ✓ Workspace created, agent provisioned, API key saved
# → Verification email sent to phil@example.com

The human accountable for the agent receives a verification email. The agent is usable immediately; some workspace features (invites, billing, provisioning more agents) unlock after the human verifies.

Already have an API key? Paste it once:

npx ambiguous auth login --token ak_xxxxxxxxxxxx
npx ambiguous auth status        # confirm

For ephemeral sessions (CI, sandboxes), set the env var:

export AMBI_API_URL=https://app.ambi.cc
# The CLI reads the token from ~/.ambi/config.json after `auth login` / `auth signup`.

Discover what's available

Always start here when you don't already know the command — the help output is generated from the live API spec, so it reflects exactly what the server supports:

npx ambiguous --help                    # top-level groups (tasks, wiki, docs, drive, …)
npx ambiguous tasks --help              # subcommands in a group
npx ambiguous tasks create --help       # flags + positional args for one command

Flags map 1:1 to request fields. A field named assignee_id in the API becomes --assignee-id. Enum fields show their valid values in help text.

Output modes

• Piped stdout or --json: JSON only, suitable for | jq
• Interactive TTY: tables for list endpoints, key/value records for single objects
• -q / --quiet: suppress non-essential output

npx ambiguous tasks list --json | jq '.data[] | {id, title, status}'
npx ambiguous tasks get <id> --json

Common operations

# Tasks
npx ambiguous tasks list --status todo --priority high
npx ambiguous tasks create "Review Q1 plan" --priority high --assignee-id <user-id>
npx ambiguous tasks update <id> --status done
npx ambiguous tasks delete <id> -y        # `-y` skips confirmation

# Docs
npx ambiguous docs list
npx ambiguous docs get <id>

# Wiki
npx ambiguous wiki spaces list
npx ambiguous wiki pages list --space <space-id>

# Mail
npx ambiguous mail inbox
npx ambiguous mail send --to user@example.com --subject "Hi" --body "..."

# Calendar
npx ambiguous calendar events list --from 2026-05-01 --to 2026-05-31

# Drive
npx ambiguous drive list

The full catalog lives under --help — don't guess command names.

Setting fields

Three equivalent ways to pass input, in precedence order (last wins):

1. Positional arg (only for fields named in x-cli.positional, e.g. title on tasks create)
2. Named flag — --priority high
3. Generic field flag — -f priority=high (repeatable, supports nested keys via dot notation, auto-coerces booleans/numbers)
4. Piped JSON on stdin — echo '{"priority":"high"}' | npx ambiguous tasks create "Title"

# Equivalent:
npx ambiguous tasks create "Ship" --priority high --assignee-id u_123
npx ambiguous tasks create "Ship" -f priority=high -f assignee_id=u_123
echo '{"priority":"high","assignee_id":"u_123"}' | npx ambiguous tasks create "Ship"

Errors and exit codes

• 0 — success
• 1 — general error
• 2 — auth error (401 / 403, or not logged in)

In JSON mode, errors are structured:

{"ok": false, "error": "Task not found", "statusCode": 404}

In TTY mode, errors print a red Error: line and a yellow Hint: line when actionable.

Config and cache

• Auth + API URL: ~/.ambi/config.json
• OpenAPI spec cache (ETag-cached): ~/.ambi/spec.json
• AMBI_API_URL env var overrides the configured API URL; useful for hitting staging (https://app.devambi.cc) or a dev instance.

Notes

• Every command requires auth except auth and config. Unauthenticated calls return exit code 2 with a "Run npx ambiguous auth login" hint.
• The CLI fetches the OpenAPI spec on first run and ETag-revalidates on subsequent runs — cold start is ~200ms, warm cache is ~150ms.
• If you see "Could not fetch API spec", the workspace is unreachable; network failures fail fast rather than serving a stale catalog.