Tiden CLI

The tiden CLI is a standalone REST client. It does not depend on protobuf code generation or backend source code.

Install

brew install --cask qase-tms/tap/tiden
curl -fsSL https://tiden.ai/install.sh | bash

Windows:

irm https://tiden.ai/install.ps1 | iex

Configure

Preferred:

tiden setup

Manual:

tiden config set baseUrl https://app.tiden.ai
printf '%s' "$TOKEN" | tiden config set apiToken -
tiden config verify

Add --workspace-id <id> to config set apiToken and config set baseUrl when more than one workspace login is stored. See Set up the CLI for headless setup with tiden setup --api-token.

Global flags

Flag	Purpose
--base-url, -u	API base URL
--api-token, -t	API token
--workspace-id, -w	Default workspace
--timeout	Per-request timeout such as 30s
--format, -f	json or text; defaults adaptively (see Output format). run results also accepts tree; impact also accepts markdown and github
--verbose	Full per-item progress narration instead of the single-line spinner

Output format

--format picks its default from whether stdout is a terminal:

• stdout is a terminal — default is text, the styled human rendering.
• stdout is piped or redirected (scripts, CI, AI coding agents) — default is json, byte-identical to earlier releases.
• tiden setup and tiden doctor always default to text.

Precedence, highest first:

1. An explicit --format json|text flag.
2. TIDEN_FORMAT=json|text (any other value is ignored).
3. setup / doctor's own text default.
4. The adaptive default above.

--format json is the stability promise. Anything that parses tiden's stdout should pass it explicitly rather than rely on stdout not being a terminal — some agent harnesses run shell commands under a pseudo-terminal, which tiden correctly reads as interactive. Piped and non-interactive invocations are otherwise unaffected; only running tiden yourself at a shell prompt changes.

Environment variables

Beyond TIDEN_BASE_URL, TIDEN_API_TOKEN, TIDEN_WORKSPACE_ID, and TIDEN_TIMEOUT, the CLI honors:

Variable	Effect
TIDEN_FORMAT=json|text	Pins the output format, overriding the adaptive default
TIDEN_FORCE_TTY=1	Forces the styled rendering even when stdout/stderr are piped
TIDEN_NO_PROGRESS=1	Disables the progress spinner
TIDEN_ACCESSIBLE=1	Switches interactive prompts to a screen-reader-friendly mode
NO_COLOR	Disables color
CLICOLOR / CLICOLOR_FORCE	Standard CLICOLOR conventions; CLICOLOR_FORCE=1 forces color when piped
CI	Disables the progress spinner

Styling degrades on its own: color is downsampled or stripped to match the terminal, and the Unicode status symbols fall back to ASCII outside a UTF-8 locale. Nothing carries meaning through color alone, so output stays legible with NO_COLOR set.

Command groups

tiden config show|set|verify
tiden setup
tiden doctor
tiden auth login
tiden auth logout
tiden auth me
tiden workspace list|use
tiden product list|create|bind
tiden spec list|get|create|update|attribute|push|resume|rollback
tiden test list|get|create|delete|link-spec|unlink-spec|derive-links|ingest|push|resume|rollback|apply-pending-links|merge|unmerge|merges
tiden branch list|create|update|close|delete|merge-preview|merge|link-proposals list|link-proposals review
tiden component list|create|update
tiden environment list|create|get|delete
tiden release list|create|get|issues|capture
tiden issue list|get|events|event|stats|fix-context|resolve|ignore|reopen
tiden gate check|features|feature
tiden run list|get|create|exec|report|results|watch|complete|abort|delete|upload|attachment
tiden coverage-gaps
tiden trace
tiden impact
tiden draft dry-run
tiden agent types|config list|config create|config delete|run|runs|run-status
tiden intent start|refine|reconcile|nudge|resume|capture|distill|auto|hold|reopen|install|uninstall|status|captures list|captures prune
tiden skill list|install|update|uninstall
tiden permissions install|uninstall|status
tiden version

tiden spec was named tiden requirement before requirements were renamed to specs. The old names still work as aliases: tiden requirement, tiden requirements, tiden test link-requirement and unlink-requirement, and old flags such as --requirement-id for --spec-id.

tiden test merge, unmerge, and merges combine, restore, and list test cases. See How Tiden identifies a test case.

The MCP server is no longer a tiden subcommand. Use the standalone tiden-mcp-server binary.

Issue command notes

• Raw event payloads are omitted by default. issue get, issue events, and issue event strip the full raw event JSON unless you pass --payload. Symbolicated stack frames are always included, so the useful part of an occurrence is there without the bulk. issue fix-context never returns the raw payload.
• --environment, --release, and --component accept names as well as IDs. A value that looks like an ID is used as-is; anything else is resolved case-insensitively against the product's environments, releases, and components. An unknown name fails with the list of valid values instead of silently returning everything.
• --platform takes repeated or comma-separated values.
• --level is deprecated and ignored. Issues are no longer filtered by level; the flag is still accepted so existing scripts keep working. CLI versions before this change still send it, and the API rejects it, so upgrade the CLI if issue list --level fails.
• issue resolve, issue ignore, and issue reopen accept several issue IDs at once. Passing more than one also needs a product, from --product-id or from the repository binding.

For the agent-driven workflow these commands were built for, see Triage issues with an agent.

Component command notes

• --component-path scopes a component to paths in its repository, for tests and changed files.
• --runtime-path sets the path prefixes that deployed code reports in stack frames, such as messaging_service/. Tiden uses them to attribute errors to the component. Repeat the flag for more paths. On component update, the values replace the list, and --runtime-path "" clears it.

tiden component update --id <component-id> --runtime-path messaging_service/

See How errors get a component.

Intent hold and reopen

• tiden intent hold --reason "<why>" pauses the automatic merge of an intent branch. --for <duration> takes days or hours (3d, 12h) and defaults to 7d. --until <date> sets an end date instead. A hold an agent sets lasts at most 7 days; a person can hold an intent for up to 30 days. Tiden refuses a longer hold and the command shows its message. --intent <branch> or --session <id> names the intent.
• tiden intent hold --clear releases the hold and takes the same selectors.
• A hold on a merged branch exits with code 3 and points to tiden intent reopen. A hold on a branch a person closed also exits with code 3 and points to tiden intent start. An abandoned intent that receives a hold is open again.
• tiden intent reopen "<objective>" starts a new intent that continues a merged one. tiden intent continue refuses a merged intent and names reopen, or names the successor intent when a checkpoint merge created one.

See Hold an automatic merge and Branches.

Impact

tiden impact (tiden 0.45.0 or newer) lists the specs a diff affects, from the source anchors of the changed files on main: --base <ref>, --staged, paths, or all uncommitted changes. In a pull or merge request pipeline it takes the base from GITHUB_BASE_REF or CI_MERGE_REQUEST_TARGET_BRANCH_NAME. --fail-on affected|uncovered|unanchored exits 3 when the policy matches. See List the specs a pull request affects.

Parent specs in CLI output

A parent spec with child specs and no tests of its own takes its coverage from its child specs. tiden coverage-gaps and tiden trace print it as covered ↳ 2/2 child. The working contract's coverage gaps and tiden intent lookup add "(through child specs)". With --format json, the fields are viaChildren, childSpecs, and childSpecsCovered; session progress rows also carry childrenCarry, and feature-context coverage carries viaChildrenIds. See Parent specs.

Exit codes

Code	Meaning
0	Success
1	General error
2	Auth error: the token was rejected (401), or no logged-in account can see the workspace or product. A token refused by its limits (403) returns 1; see API token is refused with 403
3	Action required: tiden intent hold on a branch that already merged; tiden gate check that did not pass; tiden release capture or tiden gate check --release while the release gate is pending; tiden impact --fail-on whose policy matched
130	Interrupted

Branch notes

Spec and test commands support branch flags where branch-scoped behavior exists. Component branch flags are not yet wired in the CLI.

• tiden branch update --name <branch> changes the description in place: --description "<text>", or --description-file <path> (- reads standard input). --description "" clears it. The branch keeps its ID, links, review, and run history.
• tiden branch close --name <branch> ends a branch without deleting it. Repeating it changes nothing, and main is refused before any request. See Closed branches.
• tiden intent continue and tiden intent hold refuse a branch a person closed and point to tiden intent start. A branch Tiden abandoned is not refused: it reopens on activity.

For runs on a GitHub merge queue, see GitHub merge queue.