# 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.

## 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).