# Raq.com CLI

The `raq` command provides a shell interface alongside MCP. Both use the same account permissions, authorised tool catalogue, audit logging and execution gateway. The CLI discovers tools dynamically, so new modules do not require a CLI release.

## Install and update

Requires Node.js 22 or later, Bash and macOS or Linux (Windows users can use WSL). Download and inspect the installer, then run it:

```sh
curl --fail --silent --show-error https://raq.com/cli/install -o raq-install.sh
less raq-install.sh
bash raq-install.sh
raq --version
raq doctor
```

The installer verifies the Ed25519-signed release policy, manifest and individual files. Run the same installer to update; credentials are preserved. The standard installation is `~/.raq-cli`, with a `raq` symlink on PATH. This private package is distributed through Raq.com's signed release service, not npm. Version 0.2.1 is prepared in the repository; the public installer serves it only after an authorised deployment.

## Connect and choose an account

```sh
raq login
raq accounts
raq accounts --use my-team
raq whoami
```

Browser login uses a loopback callback, a random state and S256 PKCE. `--no-browser` prints the approval link without launching a browser. For a remote shell where loopback is unavailable, use `raq login --paste` for hidden token entry or pipe one token to `raq login --token-stdin`. Obtain that token through AI Connections. Tokens are never accepted as command-line arguments or printed in responses.

A login with multiple accounts requires explicit selection. Commands accept `--account <slug-or-id>`. It takes precedence over JSON `account_id`, then the environment/default account. The selected account is verified and applied to the gateway and nested tool arguments, including watched status calls.

`raq logout` deletes local credentials. `raq logout --revoke` first revokes the server token; a failed revocation returns nonzero and retains the credential for a retry. Revoke access in AI Connections if a machine is lost.

## Discover and call tools

```sh
raq modules
raq search "list task boards"
raq schema task_board_list_boards
raq schema task_board_list_boards --example
raq call task_board_list_boards --data '{}' --json
raq call task_board_list_boards --field limit=10
raq call task_board_list_boards @arguments.json
cat arguments.json | raq call task_board_list_boards --stdin
```

`--data` takes a JSON object. Repeat `--field key=value` to add or override fields; booleans, numbers, null, arrays and objects are decoded. Input merges in this order: `--data`, stdin, legacy `--json '{...}'`, fields, positional `@file` inputs. Extra bare arguments and unknown options fail before a network request. The legacy `--json '{...}'` spelling is normalised to `--data` at dispatch; new scripts should use `--data` and reserve `--json` for output.

Tool annotations determine confirmation. A potentially destructive tool requires an interactive confirmation or explicit `--yes` in automation; a suggestive tool name is not the security decision. `--watch` follows status-like next steps only after the server confirms they are read-only. It never automatically follows a generation or other write. Watch is bounded to 20 minutes.

`raq upload ./report.pdf` streams directly to storage, then confirms a permanent private File Drop item. `--public` opts into sharing and `--mime-type` supplies a MIME type when local detection is unavailable. No Raq.com bearer credential is sent to storage. Failed transfers are not confirmed. `raq open`, `raq recent` and `raq handoff` help locate and share artefacts. New local call history stores only artefact metadata, without full arguments or result content. Older history files may still contain content recorded by earlier versions.

## Agent Brain sync

With Agent Brain enabled for your account, use a project directory you control:

```sh
raq sync --account my-team --targets claude,codex --dry-run
raq sync --account my-team --targets claude,codex
raq sync --propose --reason "Clarify the account review step."
```

`raq sync` writes approved active instructions and complete skill sources to the selected agents' native paths. Targets are `claude`, `codex`, `cursor`, `copilot`, `gemini` and `antigravity`; first use selects all targets unless specified. `--directory <path>` selects an existing directory. Agent rules and file discovery differ by client, so writing these files does not prove the client loaded or followed every instruction.

First use includes team material only. `--include-personal` also writes your personal material into the project files, which may be committed or shared. Review that disclosure before using it. `--team-only` removes unchanged personal material on the next sync. Target and personal selections persist for that directory when flags are omitted. The manifest is bound to the current authenticated user, account, server and directory; a different binding requires a separate directory.

Local edits are never silently overwritten. Changes to instruction text, skill descriptions and text files under managed `references/` or `scripts/` become exact-version proposals with `--propose --reason`. New supporting files are included; script source is not executed and environment declarations contain names only. Divergent edits in two native copies need resolving locally. Missing skill entry files or ownership blocks are conflicts: disable or archive the item in Raq.com rather than deleting its marker locally. New items and item renames are created in Raq.com.

A person approves proposals in the Agent Brain workspace. Until then, the local edit remains unapproved and ordinary sync refuses to replace it. Sync again after approval. Retries with unchanged edits and reason reuse the saved request receipt; a rejected proposal needs a revised edit or reason. A newer approved version causes a conflict rather than accepting an edit based on an old version.

Dry run changes no files and sends no proposals. Mutating sync uses a private lock, atomic replacement and a recovery journal under `.raq/brain/state`; interrupted operations recover on the next sync using the same account and directory. If a file was edited after interruption, recovery keeps the edit and journal for review. Keep this state private: it contains accepted source text and proposal receipts. Its ignore file excludes new state from Git, and sync refuses state already tracked by Git. Native instruction and skill files remain available to your usual project workflow.

This command is implemented in CLI source; it will be available from the public installer after the next signed release is built and an authorised deployment publishes it.

## Private Claude Code marketplace

In Agent Brain, create a Claude Code plugin ZIP and publish it from Import and Export. Publication selects that exact approved snapshot. New approved edits require a new export and publication; changed or withdrawn selected versions are not served. Personal skills require an explicit confirmation. The marketplace belongs to your account and user, and your signed-in CLI must have current Agent Brain read access.

Merge the generated `extraKnownMarketplaces` entry into your own Claude Code user settings, preserving existing settings. Open a new Claude Code session so startup registers the marketplace, then run the displayed `/plugin install` command inside that session. The native flow was verified with Claude Code 2.1.310. Immediately running `claude plugin install` before that first startup does not register the settings entry. Adding its bare URL can conflict with the declared helper-bearing source. Use Claude Code's marketplace controls for automatic updates.

The generated settings use `raq brain-headers --marketplace <exact-url>`. This is a native credential helper, not an interactive command: it refuses terminal output, requires Claude Code's exact `CLAUDE_CODE_MARKETPLACE_URL`, and emits a JSON header map only to the native pipe. It reads the stored CLI login, ignores `RAQ_TOKEN` and `RAQ_CLI_ENDPOINT` overrides, and refuses a different origin, marketplace path, query, fragment or archive-level invocation. No token belongs in settings or URLs. Keep your stored CLI configuration private.

Published archives are retained while the marketplace is enabled. Downloads recheck ownership, current access, the originating export connection, active items and exact revisions. Disable Marketplace stops future requests but cannot erase copies already downloaded to a machine. Installation means the skills are available, not that a model used them. The helper becomes available through the public installer with the next signed CLI release and authorised deployment.

## Automation contract

Set `RAQ_TOKEN` through your CI secret store and `RAQ_ACCOUNT_ID` to the intended account. These credentials remain in memory; they do not modify or inherit the stored identity. `RAQ_CLI_ENDPOINT` defaults to `https://raq.com`; HTTPS is required except for loopback test servers. An endpoint override cannot redirect an existing stored token to another host. `RAQ_CLI_CONFIG_DIR` isolates config and history without changing the executable installation directory.

Structured command results use JSON when piped or when `--json` / `RAQ_CLI_JSON=1` is set. Help, completion, version, `open --print` and agent-guidance previews are text outputs. `init --json` remains a change preview. Errors go to stderr (JSON in machine mode); stdout contains only successful results. `NO_COLOR` disables ANSI colour, even when empty. Broken pipes end cleanly. Ctrl-C retains the normal exit code 130.

| Exit | Meaning |
| --- | --- |
| 0 | Success |
| 1 | Invalid input, missing account selection or diagnostic failure |
| 2 | Missing, expired or insufficient credentials |
| 3 | Network, timeout, rate-limit or protocol failure |
| 4 | Server or MCP tool execution failure |

Requests time out after 1,200,000 ms; set `RAQ_CLI_TIMEOUT_MS` for a shorter automation deadline. Redirects are rejected. No request is automatically retried: a timed-out write may have completed, so inspect its result before repeating it.

## Shell completion

```sh
# Bash
source <(raq completion bash)
# Zsh, after compinit
source <(raq completion zsh)
# Fish
raq completion fish | source
```

Completions contain local command/option names and require no login. Tool discovery stays server-backed through `raq search` and `raq schema`.

## Development and release

Run `npm test --prefix raq-cli` for independent Node integration tests using loopback servers and temporary credential directories. The existing PHP CLI regression tests remain in `tests/Feature/RaqCliCommandTest.php`. CI checks source, signed release integrity and the actual signed payload. No production credentials or paid actions are used by the tests.

Bump `raq-cli/package.json`, add new runtime files to the CLI manifest list in `scripts/build-agent-releases.mjs`, then run `node scripts/build-agent-releases.mjs cli` with the existing local signing keys. Never edit a previous release. Run `node scripts/verify-agent-releases.mjs` and test the new release's entry point using `RAQ_CLI_TEST_ENTRY`. Commit source, tests, policy, signatures and the new release directory together. Publishing via a Raq.com deployment requires explicit approval.

The interface follows the [Command Line Interface Guidelines](https://clig.dev/) and uses Node's [strict argument parser](https://nodejs.org/download/release/latest-jod/docs/api/util.html#utilparseargsconfig).