taktcli

Authorized GraphQL CLI for Takt — the full Takt GraphQL surface from the shell, for agents and humans. Everything the MCP server does, and more.

The core is stdlib-only (urllib + argparse + json): a thin argv → GraphQL-over-HTTP client. Because arguments arrive as argv strings, it structurally sidesteps the MCP client-serialization bug class (arrays-as-JSON- strings, double-encoded results, the empty-string-drops-all-args bug) — an argv string simply can't be double-JSON-encoded.

The package and console-script are both named taktcli (bare takt is taken on PyPI).

Install

pip install taktcli            # stdlib-only core
pip install 'taktcli[watch]'   # + websockets, enables `taktcli watch`
pip install -e cli/            # from a monorepo checkout

Maestro/harness images ship pip install 'taktcli[watch]' — taktcli watch is the supported replacement for the retired tools/wait_for_task.py.

Quickstart

taktcli login                          # device-auth, stores ~/.takt/credentials.json
taktcli whoami                         # nickname + claims + active credential source
taktcli board --project takt           # show the board
taktcli claim takt-42                  # READY → RUNNING, prints leaseId
taktcli run takt-42                    # heartbeat the lease
taktcli done takt-42                   # mark DONE

taktcli --help (or taktcli help) lists every command; taktcli <noun> --help lists a group's verbs.

Auth

Token resolution, simplest-wins:

1. TAKT_TOKEN env → used verbatim. This is what harness containers are stuffed with; env always wins over any stored credential.
2. Else ~/.takt/credentials.json — plain JSON { "token": "<jwt>", "url": "..." }, mode 0600, written by taktcli login.
3. Else error: No Takt credentials found. Run: taktcli login (exit 3).

URL resolution mirrors it: TAKT_URL env → url in the credentials file → default https://api.takt.sh/graphql. The watch WS endpoint is derived by swapping the scheme (https → wss).

taktcli login runs the OAuth 2.0 device-authorization grant: it prints a verification URL + user code, polls until you approve in a browser, then persists the token. logout removes the stored credential; whoami prints who you are and which credential source is active.

taktcli login                                       # default endpoint
taktcli login --url http://localhost:8454/graphql   # override the endpoint
taktcli logout
taktcli whoami

Auth is the same JWT + claims used by MCP and GraphQL — taktcli adds no privilege surface. There is no claims/permission verb anywhere; admin ops are reachable via gql only if the caller's token already holds the admin claim. Long-lived bot tokens stay minted out-of-band (tools/jwt_cli.py) and dropped into TAKT_TOKEN; login is for humans and dev machines.

Passthrough — reaches 100% of GraphQL

taktcli gql + taktcli schema are a complete superset of every MCP tool: any GraphQL op MCP never wrapped is reachable here.

taktcli gql -q 'query { me { nickname claims } }'
taktcli gql -f query.graphql --var id=takt-42 --field-file description=desc.md
taktcli schema --sdl              # SDL introspection (--json for JSON)

Big markdown flows through --field-file NAME=PATH (NAME=- = stdin) — this sidesteps shell quoting and the empty-string-args bug class.

Shared I/O flags

• --var KEY=VALUE (repeatable; value parsed as JSON when valid, else string)
• --vars JSON / --vars-file PATH (- = stdin) — bulk variables
• --field-file NAME=PATH (NAME=- = stdin) — inject a file's contents as a variable; the canonical path for large markdown
• --raw — full {data, errors, extensions} envelope (default is pretty .data)
• --compact — single-line JSON

Variable precedence (lowest → highest): --vars-file < --vars < --var < --field-file.

Command surface

The CLI uses a positional namespace — taktcli <noun> <verb> [args] — so the entity is always the first token. This fixes the MCP create_wiki (Wiki) vs wiki_create (page) collision at the CLI layer. Run taktcli <noun> --help for a group's verbs.

Every MCP tool maps to a verb:

Notes:

• label create is CLI-only (the MCP server never wrapped createLabel, but the GraphQL mutation exists). label update / delete are keyed by name and resolve the id client-side via the labels query.
• The wiki page verbs take --wiki SLUG (default $TAKT_WIKI) and stream big markdown through --content-file / --old-file / --new-file (- = stdin).
• The wiki-container verbs are wikis list/create/get/update (entity = Wiki). The old workspace list/create/get verbs are a hard error naming the replacement for one release — workspace is being reclaimed to mean the tenant, and nothing else.
• project rename is name-only — slug changes are blocked on the backend.

Update a Wiki container

taktcli wikis update knowledge --name "Team knowledge"
taktcli wikis update knowledge --description "Shared documentation"
taktcli wikis update knowledge --description-file description.md
taktcli wikis update knowledge --description-file -
taktcli wikis update knowledge --new-slug team-docs --yes-rewrite-links

The current slug is required explicitly; this command does not use $TAKT_WIKI. Provide at least one field. Omitted fields are preserved; --description "" stores an empty string. --description-file reads UTF-8 text (- reads stdin) and cannot be combined with --description. Name and description require write:wiki within the token's workspace and wiki allowlist.

--new-slug requires --yes-rewrite-links; omitting confirmation exits 3 before sending a request. Confirmation does not bypass the server's human OWNER check. Actual slug changes currently return NOT_IMPLEMENTED with a clear server message on stderr and exit 1, pending mention reconciliation in takt-428. Successful metadata updates print {"updateWiki":{"slug":…, "name":…, "description":…}}; --raw and --compact follow the normal output contract. Rewrite counts and unfixable links are not returned by the current server.

Output & exit codes

Default output is pretty JSON of the unwrapped .data payload. --compact = single-line; --raw = full {data, errors, extensions} envelope; watch = NDJSON (one event per line, flushed per event).

extensions.code (e.g. LEASE_EXPIRED, ALREADY_CLAIMED) is preserved in error output so loops can branch on it.

Task monitoring — taktcli watch

Replaces the retired tools/wait_for_task.py. Streams subscription events as NDJSON and reconnects with exponential backoff on drops (e.g. deploys). Needs the [watch] extra.

taktcli watch --project takt --timeout 3600     # status changes, any task
taktcli watch --task takt-42 --task takt-43      # specific tasks
taktcli watch --project takt --event resultAdded # other subscriptions

--event defaults to taskStatusChanged. Unlike the old one-shot script, watch is a continuous stream — read NDJSON lines as they arrive and act on the first matching one; no restart-per-event. Tasks already READY when the watcher starts are not detected — check taktcli board --project takt first.

MCP coexistence

taktcli and the MCP server run side-by-side over the same GraphQL API, authenticating identically (JWT, same claims). Use either or both in one session. The MCP freeze/removal timeline lives in PRD 002 §8.

Documentation

• Usage reference: takt/context/taktcli in the Takt wiki.
• Design & rationale: takt/dev/prd-002-taktcli (PRD 002).
• Contract placement: takt/contract §4.3 — the CLI as a first-class integration interface alongside GraphQL + MCP.

Release

Push a cli-v* tag (e.g. cli-v0.1.0) — .github/workflows/cli.yaml builds cli/ and OIDC trusted-publishes to PyPI. The tag must match the version in cli/pyproject.toml (CI asserts this). The CLI has its own CI job alongside backend/plugin/frontend (npm run test:cli).