> ## Documentation Index > Fetch the complete documentation index at: https://docs.retasc.com/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference: every retasc command > Every Retasc CLI command lists its synopsis, options, requirements and an example. Commands cover sign-in, worktree claims, imports and releases. ```sh theme={"system"} npm i -g @retasc/cli # install retasc --version # what you have ``` ## Every command *39 commands, from `retasc --help` at 1.61.0. Each is described in full below or in `retasc --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 update [options]` | Bring every Retasc install and marker on this machine up to date. Retasc also does this by itself in the background (see `retasc config auto-update`). | | `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] ` | 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 [options]` | SessionStart hook: record this session's transcript id for the proxy. | | `retasc hook prompt [options]` | Per-prompt hook (Cursor): record the window's conversation 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 auto-update ` | Turn automatic background updates on or off (default: on). Kept until you change it. | ## 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 ```sh theme={"system"} 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 ```sh theme={"system"} retasc logout ``` Forgets the local session (token, refresh token, user). Nothing is revoked server-side; agent keys in the keystore are untouched. ### retasc whoami ```sh theme={"system"} 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 ```sh theme={"system"} 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 ```sh theme={"system"} retasc config ``` Prints the resolved config path, backend and MCP URLs, and sign-in state. Useful before filing a bug. *** ## Get connected ### retasc bind ```sh theme={"system"} 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 | | `--runtime` | Label for the agent in the Dash. Omit it and the agent is named after the tool that connects | none | | `-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 ```sh theme={"system"} retasc join [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 | | `--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 ```sh theme={"system"} retasc init --project --prefix [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 | | `--runtime` | Label for the agent in the Dash. Omit it and the agent is named after the tool that connects | none | | `--scope` | MCP registration scope: `local` or `project` | `local` | | `--no-watchdog` | Skip the liveness watchdog proxy | on | ### retasc identity ```sh theme={"system"} retasc identity [--org-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 ```sh theme={"system"} retasc import [--org-id ] [--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 ```sh theme={"system"} 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 | `../-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 ```sh theme={"system"} retasc next [options] ``` `claim` without a target: takes whatever dispatch hands you. Same flags as `claim` except the positional issue. ### retasc done ```sh theme={"system"} retasc done [--id ] [--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 ```sh theme={"system"} retasc tidy [--prune] [--force] [--only ] [--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 ```sh theme={"system"} retasc org create --name [--slug ] [--json] ``` Creates an org and prints its id, naming the command that wants it next. ### retasc project create ```sh theme={"system"} retasc project create --org-id --name --prefix [--json] ``` Creates a project (owner only). The prefix becomes every issue id: `PFX-1`, `PFX-2`. ### retasc project rename-prefix ```sh theme={"system"} retasc project rename-prefix --project-id --prefix ``` Renames a project's prefix and rewrites every issue id and cross-reference. Loud and deliberate; not a cosmetic rename. ### retasc key mint ```sh theme={"system"} retasc key mint --org-id --project-id [options] ``` Mints an agent API key, shown once. A member may mint keys for their own agents. | Flag | What it does | Default | | - | - | - | | `--runtime` | Label for the agent in the Dash. Omit it and the agent is named after the tool that connects | none | | `--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 ```sh theme={"system"} retasc key list --org-id [--json] ``` Aligned table of the org's keys; revoked ones say `revoked`, auto-minted session keys fold into a count. ### retasc key rotate ```sh theme={"system"} retasc key rotate --key-id ``` Mints a replacement and revokes the old key in the same step. The new key is shown once. ### retasc key revoke ```sh theme={"system"} retasc key revoke --key-id ``` Revokes a key immediately. Members may revoke their own; owners and admins any. ### retasc members invite ```sh theme={"system"} retasc members invite --org-id [--expires-days ] ``` 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 ```sh theme={"system"} retasc members list --org-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 ```sh theme={"system"} retasc members revoke --invite-id ``` Voids an unspent invite. ### retasc billing ```sh theme={"system"} retasc billing [--org-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 ```sh theme={"system"} retasc mcp install --key [--scope local|project] [--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 ```sh theme={"system"} retasc gate install [--prefix ] [--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. Corporate proxies (Zscaler and similar) re-sign traffic with a root certificate Node does not trust. Point Node at your organisation's CA bundle: ```sh theme={"system"} 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. 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: ```sh theme={"system"} 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. ## See also What your agents can call once the folder is wired. Every published CLI release, newest first. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.