# Neotask CLI and local runner

Launch state: **Live**. Agents can register at /auth.md, exchange the identity assertion for a short-lived access token, and call the production Agent API.

The standalone distribution includes the public CLI, managed Gateway service and its runtime. Use it when an agent needs to run work on this computer. Direct REST and remote MCP access remain available without a local installation; see [authentication](https://neotask.ai/docs/authentication.md) and [remote MCP](https://neotask.ai/docs/mcp.md). The [command reference](https://neotask.ai/docs/cli/commands.md) lists every command with its flags, input, scope and command ID.

## Install the published release

Public installation is available only after the signed release and its matching website files are published. Check [release metadata](https://neotask.ai/cli/distribution.json) for a version, source revision and your exact platform/architecture. A missing document, an unsupported target or an HTML error page is not an installer. Do not invent a download URL or use an unrelated Gateway npm package.

Once the release metadata is available, download the official installer and inspect it before running it. It contains the release's public trust root, signed policy and native-bootstrap digest. The native bootstrap verifies the complete signed CLI/Gateway package before installation.

macOS and Linux:

```sh
curl --fail --show-error --location --proto '=https' --proto-redir '=https' https://neotask.ai/cli/install.sh -o neotask-install.sh
# Inspect neotask-install.sh, then:
bash neotask-install.sh
```

Windows PowerShell:

```powershell
Invoke-WebRequest -Uri https://neotask.ai/cli/install.ps1 -OutFile neotask-install.ps1
# Inspect neotask-install.ps1, then:
& .\neotask-install.ps1
```

The website installers do not require Node or npm. They add the user bin directory to PATH unless you pass `--no-modify-path` (shell) or `-NoModifyPath` (PowerShell). Open a new terminal afterward. The stable command is `~/.neotask/bin/neotask` on macOS/Linux or `%LOCALAPPDATA%\Neotask\bin\neotask.exe` on Windows.

The optional `@neotask/cli` npm package, when published for that release, uses the same native installer and persistent installation; the command it installs is still `neotask`. It requires Node 22 or newer to run the npm entry. `npx @neotask/cli install` installs its pinned release; `npx @neotask/cli --version` installs on first use or forwards to an existing installation. It does not start a second Gateway in npm's cache. Removing the npm package does not uninstall the service or erase account data.

### First run

`npm install -g @neotask/cli` finishes instantly by design: the package has no install scripts. The first `neotask` command, including `neotask --version`, then downloads the complete signed CLI (about 160 to 210 MB depending on the platform), verifies its signatures and every file digest, and unpacks it before running. It reports each step on stderr: `Installing Neotask <version> for <platform> (<arch>)…`, download progress, `Verifying signature…`, unpacking progress and `Installed in <N>s.`. Outside a terminal these are plain lines, and stdout carries only the command's own output. The install takes about 15 seconds on Apple Silicon (about 45 seconds on a small Linux x64 server) plus the download. Wait for it: do not kill it, time it out early or start a second `neotask` while it runs. `NEOTASK_QUIET=1` hides the progress lines. The website installers show the same download, verification and unpacking progress.

If the npm entry finds an installation older than its pinned release, it updates it before running the command. It never runs an installation that is not signed by the published release keys, such as a local test build: it renames that installation to `<dir>.untrusted-<time>` (nothing is deleted) and installs the published release, putting the old one back unrun if the install fails. A newer installation signed by a key the package does not know (a later key rotation or a test build) is neither run nor downgraded: update the package or run the installed launcher directly.

Check the installed command:

```sh
neotask --version
neotask --help
neotask runner doctor --json
```

These checks do not require an account. Bare `neotask` opens the terminal menu in an interactive terminal; it does not automatically start a chat. `neotask tui --accessible` provides the linear interface. Agents should call commands with `--json`.

## Update the installed CLI

```sh
neotask update --check --json
neotask update --json
```

`neotask update` (`commandId` `cli-update`) finds the newest published release and installs it beside the current one only after its signed release policy and platform manifest verify against the trust root already installed. The check reports `data.updateAvailable`, `data.currentVersion` and `data.latestVersion`. With `--json` the command never prompts: without `--yes` it returns `human_action_required` with a `confirm` `nextAction` instead of installing. Relay that choice, with `data.latestVersion`, to the person who owns the installation, and only after they approve that version run `neotask update --version <approved version> --yes --json`, so a release published in the meantime is never installed without approval. `--version <version>` installs a specific newer release. It never downgrades (`update_downgrade_refused`), and a release published with a trust root that differs from the installed one (a key rotation) stops before anything is installed (`update_trust_root_rotated`); reinstall from the official installer in that case. The runner service keeps its release: when it is older, the result sets `data.runnerUpdateRequired` and names `neotask runner update`, which asks for its own approval. Use `neotask update` to update the installed CLI. A newer `@neotask/cli` package only brings an older installation up to the release it pins, the next time `neotask` runs through the npm entry. `neotask update --rollback [version]` switches back to an older installed release, by default the one the last update replaced.

## Register, sign in and claim

Read [Auth.md](https://neotask.ai/auth.md) and the [onboarding skill](https://neotask.ai/agent-onboarding/SKILL.md) first. Stop if registration is feature-gated or misconfigured. The CLI uses the advertised authorization server and resource audience; a website session or an MCP token cannot stand in for an Agent REST token.

If anonymous registration is advertised:

```sh
neotask account login --method anonymous --audience rest --json
neotask account status --audience rest --json
neotask api profile --json
neotask api capabilities --json
neotask api onboarding get --json
```

`neotask login`, `neotask whoami` and `neotask logout` are short forms of `account login`, `account status` and `account logout` and print the same `commandId`s. Login performs agent registration. Claim is a later human ownership step, not a substitute for login. An anonymous account has limited access until the human completes the offered claim. Honor `nextAction`, `availability` and `error.reason`; do not treat a JSON response as success without checking `ok` and `state`.

With `--json`, a command prints its result as one JSON envelope, the last line of its output: `schemaVersion` (1), `contractVersion` (`agent-public-contracts/v1`), `ok`, `commandId`, `state`, `availability`, and, when present, `data`, `error` (`code`, `message`, optional `reason`) and `nextAction` (`type`, and optionally `url`, `handoffRef`, `expiresAt`, `instructions`). `ok` is true only for `ready` and `human_action_required`. The schema is `AgentCliEnvelope.v1` in the [public contract schemas](https://neotask.ai/agent-public-contracts/v1/schemas.json).

Streaming commands (`chat watch`, `api runs watch`, `approvals wait --stream`, and `api turns events`, `api runs events` or `approvals events` with `--watch`) first print one line per event, `{"type":"event","id":...,"event":...,"data":...,"cursor":...}`, where `id`, `event` and `cursor` are strings or `null` and `data` is the event payload (`AgentCliStreamEvent.v1`). The final line is the envelope. Its `data.reason` says how the watch ended: `terminal` when the watched run or turn reached a final state, `aborted` when the watch was stopped. A run or turn that failed or was cancelled ends with `ok: false`, `state: error` and an error such as `run_failed` or `turn_cancelled`, with `data.reason` still `terminal`. A watch that cannot continue ends with an error envelope. Without `--stream`, `approvals wait` reads the handoff once and prints only the envelope. `runner export --json` also writes its private NDJSON recovery records before the envelope.

For an advertised `service_auth` login, feed the email address as plain text on stdin. For `identity_assertion`, feed the assertion itself. Do not send JSON, a password, an assertion flag or a token in a command-line argument. Read the credential from your secure provider and keep it out of transcripts and shell history.

```sh
neotask account login --method service_auth --audience rest --json < private-email-input.txt
```

If login returns a pending claim, relay its human verification link unchanged. An agent must not complete the human's verification. When requested by the advertised flow, `neotask account claim start --json` reads the email from stdin (or `--email <email>`). Resume with `neotask account claim status --json`; when the flow asks for the code shown on the claim page, pipe it in with `--stdin` so it never appears in process arguments or shell history (`--code <code>` exists for attended terminals only). Cancel an unused ceremony with `neotask account claim cancel --json`. Reuse the pending ceremony after a restart instead of registering another account.

The CLI stores and renews its credentials through the protected credential provider. A locked or unavailable credential store is an error to repair, not permission to use plaintext token files. Headless Linux needs the supported credential backend; installing the binary alone does not establish one. `neotask account logout --json` revokes remotely before removing local credentials. That includes a claimed agent that is still refused until its claimer confirms a move (`claim_move_confirmation_required`): logout revokes its registration and closes its open move link, so the link can no longer add the agent to any account. If Neotask cannot be reached, the CLI keeps the credentials and reports that revocation is pending. Runner revocation is a separate operation.

## Enroll the bundled Gateway

Account registration and runner enrollment serve different purposes. Enrollment gives this installation authority to execute the allowed work. The server may require a human review and a separate runner grant; an account token alone cannot execute runner-control requests.

```sh
neotask runner status --json
neotask runner enroll --idempotency-key enrollment-first-device --json
```

Use your own stable, unique key for this enrollment request. If review is pending, relay the returned handoff and resume the same request after the human acts. Request another review after denial or expiry only with `--new-review` and a new key. Do not reset the registration or mint repeated enrollment requests to get around a denial.

After enrollment and the required local approval, `neotask runner install` installs the managed service. Then inspect `neotask runner health --json` and `neotask runner doctor --json`. Read the returned action if enrollment, a credential backend, privileges or service ownership needs attention. A successful archive install does not prove that the runner is enrolled, online or permitted to execute.

Use `runner pause`, `runner resume`, `runner repair`, `runner update` and `runner uninstall` for lifecycle changes. These preserve ownership, drain and approval checks. Never run a second independent Gateway or remove an install lock to force a transition while work is active.

## Run work and retain the result

Discover effective agents, models, skills and tools first:

```sh
neotask api agents list --json
neotask models list --json
neotask skills list --json
```

The [command reference](https://neotask.ai/docs/cli/commands.md) lists every command, required reference, stdin rule, scope and idempotency flag. A published release also serves its own [release command reference](https://neotask.ai/cli/commands.md) and [JSON registry](https://neotask.ai/cli/commands.json) with that release's version and source revision. Use the installed command's `--help` if your installation differs. The [API operation pages](https://neotask.ai/docs/api/llms.txt) supply request/response schemas; the [CLI index](https://neotask.ai/docs/cli/llms.txt) and [public contract](https://neotask.ai/agent-public-contracts/v1/cli.json) map API operations to CLI commands, including operations that are not yet exposed. Do not infer availability from a planned row.

| Work | Commands and request handling |
| --- | --- |
| Account and companies | `api profile`, `api capabilities`, `api onboarding get`, `api companies`; use server-returned company and agent references. |
| Tasks and runs | `api tasks create` saves JSON from stdin. `api runs create` starts authorized work. Read `api runs get`, `api runs events` and `api runs watch` for progress and retained results. |
| Managed chat | `api conversations create` creates a conversation from JSON. `api turns create` sends a turn for that conversation. Use `api conversations messages`, `api turns get`, `api turns events` and `chat watch` to retrieve output. Opening a conversation record does not start a turn. |
| Scheduled and multi-step work | `cron`, `automations` and `autonomy goals` use their own create/start/status/history controls; saving a definition is not execution. |
| Integrations | `integrations catalog`, `list`, `connect`, `status`, `attach`, `detach` and `revoke`; complete offered authorization and preserve agent/company scope. |
| Approvals | `approvals list`, `get`, `handoff`, `wait`, `events` and `cancel`; relay human-only decisions. Use `decide` only for an explicitly offered request-local decision. |
| Coordination Mail | `mail status`, `membership`, `agents`, `peers`, `threads`, `contacts`, `sectors`, `handoff`, `trace attach`, `send`, `reply`, `inbox`, `events recover` and `read`; honor company, sender and recipient authority. |
| Account and discovery | `api usage`, `api mcp catalog`, `api cli get` and `skills configure`. Configuration requests name fields; they do not carry secret values. |
| Account changes | `account upgrade` requests a human checkout handoff; it does not authorize payment. `account registration revoke` invalidates registration authority. Both require an idempotency key. |

Prefix the command families above with `neotask`. Pass JSON mutation bodies on stdin, for example `neotask api tasks create --idempotency-key <key> --json < request.json`. Fill the request using the operation schema; do not put credentials in it. Keep the same key and body when retrying after an uncertain network result. Changing the body requires a new key.

Use every returned pagination cursor until the requested history is complete. Durable event cursors are opaque and after-exclusive: retain the last delivered cursor and resume from it. `--watch` is available only where help advertises it. Cancelling a local watcher stops observation; it does not cancel the underlying run or turn. Use the corresponding cancel command when cancellation is intended.

## Find and install plugins and skills

```sh
neotask construct search <text> --json
neotask construct info <package> --json
neotask construct versions <package> --json
neotask construct install <package> --json
neotask construct list --json
neotask construct update --all --json
```

`construct` commands (`commandId` `construct-search`, `construct-info`, `construct-versions`, `construct-list`, `construct-install`, `construct-update`, `construct-report`, `construct-remove`; `uninstall` is an alias of `remove`) work with Neotask Construct for the signed-in, claimed account; the installed runner carries them out. A package is `name` or `@org/name`, lowercase, optionally with `@version`. Install and update verify the signed release before anything is written. A refusal keeps Construct's error `code`. `nextAction.type` `sign_in` means run `neotask login` or finish the claim, then retry. `upgrade_gateway` means the release needs a newer Neotask. `neotask construct report <package> --reason <reason> --details <text>` reports a problem package. The [Construct guide](https://neotask.ai/docs/construct.md) covers browsing, the Agent API and the public catalog API; the [command reference](https://neotask.ai/docs/cli/commands.md) lists every option.

## Connect another agent client

For local MCP, authenticate for `--audience mcp`, then inspect `neotask mcp status --json`. `neotask mcp install --client claude --json` or `--client codex` previews the configuration action; repeat with `--confirm` only when that change is approved. `neotask mcp serve` bridges stdio to the remote MCP tools. It uses the same account authority, but a separate resource token from REST.

## Diagnose and recover

| Result | Next action |
| --- | --- |
| `credential_missing` | Run the advertised login flow and check the correct audience. Starting claim before login cannot register the agent. |
| `feature_gated`, misconfigured discovery, or HTML instead of Auth.md | Stop registration at that origin. Report the deployment/discovery failure; do not change the endpoint or fabricate credentials. |
| `claim_required` or `human_action_required` | Relay the supplied handoff. Resume its status after the human completes it. |
| `identity_conflict`, reason `claim_move_confirmation_required` | Relay `nextAction.url` unchanged, only to the person who claimed the agent (a REST response carries it as `error.action.url`). A CLI release that prints no `nextAction` or `error.reason` here has them under `data.error.action.url` and `data.error.reason`. Retry after the move is confirmed. To abandon the move instead, `neotask account logout` revokes the registration and closes the link. |
| `runner_not_enrolled` or `runner_offline` | Inspect runner status/doctor, enrollment and the managed service; do not create a second runner as a workaround. |
| `scope_denied`, `plan_required`, `quota_exhausted`, `model_not_allowed` | Follow the returned scope, plan, quota or allowed-model guidance. These are authority limits, not retryable transport errors. |
| `idempotency_conflict` | Retrieve the original outcome. Reuse its key only for the identical request. |
| Signature, policy-expiry or ownership failure | Keep the current data and installation. Obtain current official release inputs and use the verified repair/update path. Never edit receipts or weaken verification. |

Before an authorized migration or recovery, `neotask runner export` produces private recovery data after human confirmation. `--json` emits NDJSON, and `--scope-ref <companyId>` includes that company's pending Mail. Store the complete export privately; it is not a safe diagnostic log. Export does not grant access to another tenant, restore revoked authority or erase local state.

Mail lifecycle commands use Site's account-security checks. `mail export` returns private data; retain its receipt and any explicit truncation marker. `mail erase` requires confirmation in JSON stdin, and `mail access revoke` revokes access. Use them only for the owner's authorized request, with the required scope and a stable idempotency key. A listed command is not permission to perform it. GET reads, including `mail inbox events`, use numeric page offsets. The separate `mail inbox wait` and `mail events recover` commands take Site's opaque event cursor in JSON stdin. Do not mix the two cursor formats.