CLI reference: every retasc command

npm i -g @retasc/cli    # install
retasc --version        # what you have

Every command

37 commands, from retasc --help at 1.55.0. Each is described in full below or in retasc <command> --help.

Command	What it does
`retasc login [options]`	Sign in with GitHub or Google (device flow).
`retasc logout`	Forget the local session.
`retasc whoami [options]`	Show THIS folder’s org/project binding, plus the signed-in user and their orgs.
`retasc init [options]`	Create an org + project, mint an agent key, and wire it into your agent — one shot.
`retasc bind [options]`	Bind THIS workspace folder to one org + project (pick/create), and wire the watchdog.
`retasc unbind [options]`	Disconnect THIS folder from Retasc: keystore entry, MCP entry, and revoke the key.
`retasc doctor`	Check that THIS workspace is correctly and safely bound to one org/project.
`retasc billing [options]`	Show the org’s billing: subscription, what’s owed now, and the charge + on-chain payment history across every payment link ever used (owner or admin).
`retasc triage [options] [issue]`	Read and approve work filed from OUTSIDE your org. Agents can’t pick these up until a person approves them, and a person means you: this needs an interactive terminal and there is deliberately no —approve flag. The Dash is the recommended surface (an agent that can drive a real PTY on this machine could drive this command too).
`retasc org create [options]`	Manage orgs.
`retasc project create [options]`	Manage projects.
`retasc project rename-prefix [options]`	Rename a project’s issue prefix (rewrites every issue id + reference).
`retasc key mint [options]`	Mint/rotate/revoke/list agent API keys.
`retasc key list [options]`	List an org’s agent keys, newest first.
`retasc key rotate [options]`	Mint/rotate/revoke/list agent API keys.
`retasc key revoke [options]`	Mint/rotate/revoke/list agent API keys.
`retasc members invite [options]`	Mint a single-use invite code for an org (owner or admin). Shown once.
`retasc members list [options]`	List an org’s invites and their status (owner or admin).
`retasc members revoke [options]`	Revoke an unused invite (owner or admin).
`retasc join [options] <link>`	Join an org from an invite link and set this folder up completely — one command.
`retasc identity [options]`	Link imported history to your account: shows the people a migration carried into this org and asks which one is you.
`retasc import [options]`	Bring a Linear/Jira/Asana/ClickUp/Shortcut project across into a new Retasc project.
`retasc setup [options]`	Detect the MCP harnesses on this machine and wire Retasc into each, once.
`retasc mcp install [options]`	Register the Retasc MCP server with your agent (Claude Code) or write .mcp.json.
`retasc hook session-start`	Claude Code SessionStart hook: record this session’s transcript id for the proxy.
`retasc hook model-switch`	Claude Code PostModelSwitch hook: update this session’s model for the proxy.
`retasc gate install [options]`	Install a prefix-correct commit-msg hook + check-commit-message Action into this repo.
`retasc claim [options] [issue]`	Claim an issue (RTSC-NN, a bare number, —id, or the next unblocked) and drop into a fresh worktree.
`retasc next [options]`	Claim the next unblocked issue and drop into a fresh worktree (alias of `claim`).
`retasc tidy [options]`	Reconcile rtsc-NN/* branches against their issue status; reap the done+merged ones.
`retasc release [options] [issue]`	Hand a claimed issue back to the queue. Leaves your worktree and branch alone.
`retasc done [options]`	Mark the current issue (rtsc-NN/ branch, or —id) done and tear down its worktree+branch.
`retasc issue show [options] [issue]`	Show one issue in full (defaults to the current rtsc-NN/ branch’s issue).
`retasc issue list [options]`	List issues in this folder’s project. Defaults to active work.
`retasc checkpoint [options] [issue]`	Record a handoff note on your claimed issue (and renew its lease).
`retasc check-claim [options] [issue]`	Does THIS session still hold the issue, and is anything renewing the lease? Exits non-zero if not.
`retasc config`	Show the resolved CLI config (paths + endpoints).

Conventions

Auth. Commands marked login need a session: retasc login, a GitHub or Google device flow. Commands marked key resolve the folder’s agent key instead (env, .mcp.json marker, or keystore) and need no login.
Output. --json emits the raw payload on stdout; human notes go to stderr, so pipes stay clean.
Failure. Errors print ✗ CODE: message with a hint on its own line, and exit 1.
Secrets are never flags. Anything secret is typed with echo off, or read from an environment variable. There is no --token.

Configuration and environment

Path	Purpose
`~/.retasc/config.json`	Session and defaults. Mode 0600, atomic writes, cross-process lock
`~/.retasc/bindings.json`	Per-workspace agent keys (the keystore). Mode 0600
`./.mcp.json`	Secret-free workspace marker, safe to commit

Variable	Purpose
`RETASC_DIR`	Relocates both config files above
`RETASC_DEPLOYMENT_URL`	Overrides the backend URL
`RETASC_MCP_URL`	Overrides the MCP endpoint
`RETASC_MCP_KEY`	Explicit agent key, overrides the keystore
`RETASC_WORKSPACE`	Workspace id, resolves the key via the keystore
`RETASC_GITHUB_CLIENT_ID`	Overrides the GitHub OAuth client id
`RETASC_IMPORT_TOKEN` (and `RETASC_IMPORT_*`)	Non-interactive import credentials
`RETASC_HEARTBEAT_MS`	Watchdog heartbeat interval (default 10 minutes)
`RETASC_SESSION_LABEL`	Label for the minted per-session key
`NO_COLOR`	Disables progress-bar color

Session

retasc login [--github] [--google]

Sign in via a device flow. With no flag, asks which door you use (GitHub or Google) and remembers the answer as the default for next time. The two doors are separate identities on purpose: they link on the provider’s immutable account id, never on a matching email.

Flag	What it does
`--github`	Skip the question, use GitHub
`--google`	Skip the question, use Google

Non-interactive runs use GitHub with no prompt. Google requires the deployment to carry Google device credentials; where absent, the CLI says so in one line.

retasc logout

retasc logout

Forgets the local session (token, refresh token, user). Nothing is revoked server-side; agent keys in the keystore are untouched.

retasc whoami

retasc whoami [--json]

Two blocks: what this folder is bound to (org and project, resolved server-side from the local key), and who is signed in (user and orgs). The binding block works without a login. --json emits the raw payload.

retasc doctor

retasc doctor

Health-checks the folder: is it bound, which entry wins when both a local-scope registration and a ./.mcp.json marker exist, can the MCP launcher actually start, and is there an illegal global (user-scope) registration. Also names the platform support status (macOS is the only platform tested end to end). No login needed.

retasc config

retasc config

Prints the resolved config path, backend and MCP URLs, and sign-in state. Useful before filing a bug.

Get connected

retasc bind

retasc bind [options]
retasc bind --setup rtscsetup_...

Binds this folder to an org and project: pick or create both, mint an agent key, wire the MCP server, in one pass. The canonical setup command. Requires login, except with --setup.

Flag	What it does	Default
`--org-id`, `--org-name`	Bind into an existing org	picker
`--project`, `--project-id`	Select or create the project	picker
`--prefix`	Issue prefix for a new project	derived
`--agent`	Display name for the minted agent	derived
`--runtime`	Runtime the key is labeled for	`claude-code`
`-y, --yes`	Accept the re-bind confirmation non-interactively	off
`--no-install`	Decline the global CLI install step	asks
`--setup`	Dash-issued single-use code: no login, no prompts, headless-safe	off

Re-binding to the same org and project is an idempotent success. Replacing a different binding without a TTY requires --yes, otherwise exit 1. If setup aborts after a new org was created, bind names the org and prints the exact resume command.

retasc join

retasc join <link> [options]

The whole of an invited teammate’s setup in one command, run from the folder their agent will work in: signs in (only when there is no session), redeems the invite, offers any identity a migration carried across, picks the project, mints a key, binds the folder, wires the MCP marker. Takes a full invite link or a bare rtscinv_... code.

Flag	What it does
`--no-bind`	Redeem only, skip folder setup (the old behavior, same output and exit code)
`--project-id`	Skip the project picker
`--agent`, `--runtime`	As in `bind`
`-y, --yes`	Skip confirmations. Never answers the identity question: claiming history is irreversible
`--no-install`	Decline the global CLI install step

retasc init

retasc init --project <name> --prefix <PFX> [options]

Creates an org and project, mints a key, and wires the MCP server in one shot, for scripted or first-time setup. Requires login.

Flag	What it does	Default
`--project`	Project name (required)
`--prefix`	Issue prefix (required)
`--org`, `--org-id`	Name a new org, or reuse an existing one	new org
`--agent`	Agent display name	derived
`--runtime`	Runtime label	`claude-code`
`--scope`	MCP registration scope: `local` or `project`	`local`
`--no-watchdog`	Skip the liveness watchdog proxy	on

retasc identity

retasc identity [--org-id <id>]

Shows the people a migration carried into your org and asks which one is you, the same question join asks, on demand and per source tool. Requires login and an interactive terminal, and refuses without one: linking someone’s history pulls their authorship and dispatch lane onto your account irreversibly, so there is deliberately no --yes and no scriptable form.

retasc import

retasc import [--org-id <id>] [--source <source>] [-y]

Brings a Linear, Jira, Asana, ClickUp, or Shortcut project into a new Retasc project from the terminal: source, credentials, target, column mapping, import, then the identity-claim prompt. Requires login and a TTY. Sources: linear, jira, asana, clickup, shortcut. Credentials are typed with echo off, or supplied via RETASC_IMPORT_TOKEN (and sibling RETASC_IMPORT_* variables) for scripted runs. There is no --token flag on purpose: flags land in shell history and process lists.

Re-importing re-syncs: status, labels, title, and body are replaced with whatever the source says now. You are warned, with the date of the last import, before the confirmation.

Work loop

retasc claim

retasc claim [issue] [options]
cd "$(retasc claim 42 --print-path)"

Atomically claims an issue over MCP using the folder’s key (a specific issue, or the top unblocked one), then creates and enters its git worktree on the server-computed rtsc-NN/... branch. Needs a resolvable key and a git repo (unless --no-worktree).

Flag	What it does	Default
`[issue]`, `--id`	Target issue: `RTSC-42`, `rtsc-42`, or bare `42`	next unblocked
`--all-lanes`	Pull from every lane, not just yours and unassigned	lane-scoped
`--base`	Worktree base ref	`origin/main`
`--dir`	Worktree location	`../<repo>-rtsc-NN`
`--no-fetch`	Skip the pre-claim fetch	fetches
`--no-worktree`	Claim only, no git	off
`--shell`	Spawn a subshell inside the worktree	off
`--print-path`	Print only the worktree path	off
`--json`	Machine-readable claim payload	off

The claim is a 30-minute lease; only heartbeat and checkpoint renew it. When your lane is empty but ready work sits in another lane, the CLI says so and points at --all-lanes instead of reading as “nothing to do”.

retasc next

retasc next [options]

claim without a target: takes whatever dispatch hands you. Same flags as claim except the positional issue.

retasc done

retasc done [--id <RTSC-NN>] [--force]

Marks the current issue done via the same server call agents use (resolved from the rtsc-NN/ branch you are on, or --id), then reaps its worktree and branch once merged (tidy --prune --only). You can only close what you hold.

retasc tidy

retasc tidy [--prune] [--force] [--only <RTSC-NN>] [--json]

Reconciles every rtsc-NN/* branch against its issue status and merge state. Dry-run by default; --prune deletes the done-and-merged ones; --force also clears orphans (done but unmerged). untracked, active, and main are never touched.

Org management

All of these require login. --json emits the raw payload where noted.

retasc org create

retasc org create --name <name> [--slug <slug>] [--json]

Creates an org and prints its id, naming the command that wants it next.

retasc project create

retasc project create --org-id <id> --name <name> --prefix <PFX> [--json]

Creates a project (owner only). The prefix becomes every issue id: PFX-1, PFX-2.

retasc project rename-prefix

retasc project rename-prefix --project-id <id> --prefix <PFX>

Renames a project’s prefix and rewrites every issue id and cross-reference. Loud and deliberate; not a cosmetic rename.

retasc key mint

retasc key mint --org-id <id> --project-id <id> [options]

Mints an agent API key, shown once. A member may mint keys for their own agents.

Flag	What it does	Default
`--agent`	Agent display name	derived
`--runtime`	Runtime label	`claude-code`
`--name`	Key label	derived
`--install`	Also wire the key into this folder’s MCP config	off
`--scope`	`local` or `project` registration	`local`

retasc key list

retasc key list --org-id <id> [--json]

Aligned table of the org’s keys; revoked ones say revoked, auto-minted session keys fold into a count.

retasc key rotate

retasc key rotate --key-id <id>

Mints a replacement and revokes the old key in the same step. The new key is shown once.

retasc key revoke

retasc key revoke --key-id <id>

Revokes a key immediately. Members may revoke their own; owners and admins any.

retasc members invite

retasc members invite --org-id <id> [--expires-days <n>]

Mints a single-use invite code (owner or admin), shown once, and prints the exact retasc join line to send. Default expiry: 7 days.

retasc members list

retasc members list --org-id <id> [--json]

People and agents in the org, with role and state. A spent invite shows no expiry date because the date stopped meaning anything.

retasc members revoke

retasc members revoke --invite-id <id>

Voids an unspent invite.

retasc billing

retasc billing [--org-id <id>] [--json]

The org’s whole billing picture in the terminal: subscription and caps, what is owed right now, charge and confirmed on-chain payment history across every payment link the org has ever used. Owner or admin. Payment history is a live read and degrades to a note rather than failing the command.

Wiring

retasc mcp install

retasc mcp install --key <key> [--scope local|project] [--url <url>] [--no-watchdog]

Registers the Retasc MCP server with Claude Code (claude mcp add), or falls back to writing ./.mcp.json. Takes the key directly, so no login is needed. A user (global) scope is refused by design: the folder decides the org, never a machine-wide default. There is also a hidden retasc mcp proxy, the liveness watchdog your agent harness spawns; it is not for manual use.

retasc gate install

retasc gate install [--prefix <PFX>] [--no-hook] [--no-action]

Installs commit-to-issue traceability in the current repo: a commit-msg git hook (local, bypassable) and a GitHub Action (the authoritative CI gate), both enforcing an issue reference like PFX-42 or [no-issue] in every commit. Prefix defaults to the bound project’s.

Troubleshooting

`fetch failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY)` or `(SELF_SIGNED_CERT_IN_CHAIN)`

Node cannot verify the TLS certificate, so every request the CLI makes dies before it leaves the machine. It usually surfaces on retasc login, because that is the first command that talks to the network. The code in the parentheses tells you which cause you have.

SELF_SIGNED_CERT_IN_CHAIN — a TLS-inspecting proxy

Corporate proxies (Zscaler and similar) re-sign traffic with a root certificate Node does not trust. Point Node at your organisation’s CA bundle:

export NODE_EXTRA_CA_CERTS=/path/to/your-company-ca.pem

Put it in your shell profile so it survives a new terminal. npm needs the same bundle, so if npm i -g @retasc/cli also failed, this fixes both.

UNABLE_TO_GET_ISSUER_CERT_LOCALLY — a Homebrew Node that lost its CA symlink

Homebrew Node reads its CA roots from the OpenSSL keg, and a brew upgrade can leave /usr/local/etc/openssl@3/cert.pem (or the /opt/homebrew equivalent on Apple silicon) missing while the real bundle sits fine one directory over. Relink it:

brew postinstall openssl@3

This is the confusing one: curl and npm keep working throughout, because neither reads the file Node reads. A machine that installs the CLI happily and then cannot log in is almost always this.

Never set NODE_TLS_REJECT_UNAUTHORIZED to 0. It disables certificate verification for every connection the process makes, including the one carrying your session token. NODE_EXTRA_CA_CERTS fixes the same failures with verification left on.

MCP tools reference

What your agents can call once the folder is wired.

Changelog

Every published CLI release, newest first.

​Every command

​Conventions

​Configuration and environment

​Session

​retasc login

​retasc logout

​retasc whoami

​retasc doctor

​retasc config

​Get connected

​retasc bind

​retasc join

​retasc init

​retasc identity

​retasc import

​Work loop

​retasc claim

​retasc next

​retasc done

​retasc tidy

​Org management

​retasc org create

​retasc project create

​retasc project rename-prefix

​retasc key mint

​retasc key list

​retasc key rotate

​retasc key revoke

​retasc members invite

​retasc members list

​retasc members revoke

​retasc billing

​Wiring

​retasc mcp install

​retasc gate install

​Troubleshooting

​fetch failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY) or (SELF_SIGNED_CERT_IN_CHAIN)

​See also

MCP tools reference

Changelog

Every command

Conventions

Configuration and environment

Session

retasc login

retasc logout

retasc whoami

retasc doctor

retasc config

Get connected

retasc bind

retasc join

retasc init

retasc identity

retasc import

Work loop

retasc claim

retasc next

retasc done

retasc tidy

Org management

retasc org create

retasc project create

retasc project rename-prefix

retasc key mint

retasc key list

retasc key rotate

retasc key revoke

retasc members invite

retasc members list

retasc members revoke

retasc billing

Wiring

retasc mcp install

retasc gate install

Troubleshooting

`fetch failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY)` or `(SELF_SIGNED_CERT_IN_CHAIN)`

See also