# CLI Reference

Command surface defined in packages/nikcli/src/index.ts and packages/nikcli/src/cli/cmd.

## Entry Point

Running `nikcli` without a subcommand opens the default terminal UI (TUI) in the current directory. Pass an optional project path to open the TUI in another directory. Global flags `--print-logs` and `--log-level` apply to every command.

Terminal

bash 

```
nikcli                    # open TUI in current directory
      nikcli /path/to/project   # open TUI in another project
      nikcli --help             # list all commands
      nikcli completion         # generate shell completion script
```

$ shell · paste into your terminal

Default TUI

The default TUI command is `$0 [project]` and accepts session, model, agent, continue, prompt, and network flags. All options available to `nikcli run` are also accepted here.

## Interactive Workflows

| Command | Purpose |
| --- | --- |
| `nikcli [project]` | Open the TUI in the current or specified project directory. |
| `nikcli run [message..]` | Run a one-shot prompt without entering the TUI. |
| `nikcli run --attach <url>` | Connect a one-shot run to a running nikcli server. `--attach` is a flag on `run`, not a separate command. |
| `nikcli session list` | List past and active sessions. |
| `nikcli quickstart` | Interactive walkthrough for first-time users. Accepts `--skip-checks` and `--dry-run`. |
| `nikcli pr <number>` | Fetch and checkout a GitHub PR branch, then launch nikcli in the resulting worktree. |

Terminal

bash 

```
nikcli run "audit this repo and summarize risks"
      nikcli run --attach http://127.0.0.1:4096 "summarize the open work"
      nikcli quickstart --skip-checks
      nikcli pr 42
```

$ shell · paste into your terminal

## Autonomous & Scheduled

`goal` drives the agent autonomously until a verifiable condition is met. `routine` manages saved prompts with scheduled (cron) or API triggers.

| Command | Purpose |
| --- | --- |
| `nikcli goal [condition..]` | Work autonomously until the stated condition is met. Flags: `--continue`, `--session`, `--model`, `--agent`, `--variant`, `--token-budget`, `--format`. |
| `nikcli routine list` | List all routines for the current project. |
| `nikcli routine create` | Create a routine interactively or with flags. See the [Routines](/docs/routines) page. |
| `nikcli routine get <id>` | Show details of a specific routine. |
| `nikcli routine run <id>` | Trigger an immediate run of a routine. |
| `nikcli routine pause <id>` | Pause a routine (disables its scheduled triggers). |
| `nikcli routine resume <id>` | Resume a paused routine. |
| `nikcli routine delete <id>` | Delete a routine (alias: `rm`). Prompts for confirmation unless `--yes` is passed. |

Terminal

bash 

```
nikcli goal "all tests pass and no lint errors"
      nikcli goal --token-budget 50000 "fix the failing integration test"
      nikcli routine create --name "daily review" --prompt "summarize recent changes" --cron @daily
      nikcli routine run rtn_abc123
```

$ shell · paste into your terminal

## Missions

A [Mission](/docs/missions) is a high-altitude workflow that decomposes a goal into milestones, each holding a DAG of features, with a validation checkpoint per milestone. `nikcli mission` is a thin headless wrapper over the mission orchestrator (`packages/nikcli/src/mission/`).

| Command | Purpose |
| --- | --- |
| `nikcli mission` | Open the headless mission manager: list, status, quick actions. |
| `nikcli mission new [-f file] [--brief …] [--model …] [--agent …]` | Create a mission from a brief. With `-f` the brief is read from a file; otherwise it is read from `--brief` or stdin. `--model` and `--agent` set the worker defaults. |
| `nikcli mission start <id>` | Begin orchestrating the mission. The mission moves from `pending` to `running`. |
| `nikcli mission pause <id>` | Pause a running mission. In-flight features finish; no new features start. |
| `nikcli mission resume <id>` | Resume a paused mission. |
| `nikcli mission cancel <id>` | Cancel the mission. In-flight workers are aborted via `prompt.cancel`. |
| `nikcli mission get <id>` | Show progress, current milestone, current feature, statuses, and last error. |
| `nikcli mission list` | List all missions in the current project with their runtime status. |

Terminal

bash 

```
# Draft a mission from a brief file and start it
      nikcli mission new -f ./brief.md --agent build --model anthropic/claude-sonnet-4.5
      nikcli mission start mss_abc123
      nikcli mission get mss_abc123
```

$ shell · paste into your terminal

## Loops

A [Loop](/docs/loops) is a named, persisted workflow that runs an ordered list of stages, each of which is a single `goal` command. The headless LoopEngine owns the interval timers, so loops keep running when the TUI is closed.

| Command | Purpose |
| --- | --- |
| `nikcli loop list` | List all loops for the current project. |
| `nikcli loop create` | Create a loop interactively or with flags. Flags: `--name`, `--stage` (repeatable), `--every`, `--max-runs`, `--timeout`. |
| `nikcli loop get <id>` | Show full definition, runtime status, and the last few runs. |
| `nikcli loop run <id>` | Trigger an immediate run. Accepts `--text` to append one-off context to this run. |
| `nikcli loop pause <id>` | Stop firing triggers. In-flight runs are not aborted. |
| `nikcli loop resume <id>` | Re-enable the loop's triggers. |
| `nikcli loop cancel <run-id>` | Cancel an in-flight run. |
| `nikcli loop delete <id>` | Delete the loop and its run history. Prompts for confirmation unless `--yes` is passed. |

Terminal

bash 

```
# Two-stage loop that triages issues then drafts a fix every 30 minutes
      nikcli loop create --name "triage-and-fix" \
        --stage "triage:plan:Triage open issues and rank by impact" \
        --stage "draft-fix:build:Open a draft PR for the top issue" \
        --every 30m

      nikcli loop run lop_abc123
      nikcli loop pause lop_abc123
      nikcli loop delete lop_abc123 --yes
```

$ shell · paste into your terminal

## Services & Remote

| Command | Purpose |
| --- | --- |
| `nikcli serve` | Start the local HTTP API server. |
| `nikcli web` | Start the local web UI. |
| `nikcli companion serve` | Boot the server with the companion web UI enabled. |
| `nikcli companion open` | Open the companion UI in the browser. |
| `nikcli mobile serve` | Serve the mobile API host for app pairing. |
| `nikcli mobile pair` | Generate a mobile pairing QR code. |
| `nikcli mobile token list` | List active mobile pairing tokens. |
| `nikcli mobile token revoke` | Revoke a mobile pairing token. |
| `nikcli workspace-serve` | Expose workspace event streams for remote consumers. |
| `nikcli remote start` | Start a terminal or mobile remote control session. |
| `nikcli remote stop` | Stop the active remote session. |
| `nikcli remote status [--json]` | Show remote session status and QR code. |
| `nikcli remote share` | Print the shareable session link and copy it to the clipboard. |
| `nikcli remote attach <sessionId>` | Attach to an existing remote session by ID. |
| `nikcli acp` | Start the ACP server. |
| `nikcli mcp` | Start the MCP server. |

Terminal

bash 

```
nikcli remote start --name my-session --mobile
      nikcli remote start --cloud --cloud-url https://relay.example.com --cloud-token TOKEN
      nikcli remote status --json
      nikcli remote share
      nikcli remote attach SESSION_ID
```

$ shell · paste into your terminal

remote attach

`remote attach <sessionId>` is registered in the command surface but the underlying session-join flow is not yet implemented. The command prints a message and exits.

## Integration & Automation

| Command | Purpose |
| --- | --- |
| `nikcli connectors list` | List configured service connectors. |
| `nikcli connectors add` | Add a new connector interactively. |
| `nikcli connectors auth <name>` | Authenticate an existing connector. |
| `nikcli connectors logout <name>` | Revoke connector credentials. |
| `nikcli bot list` | List configured chat bots. |
| `nikcli bot add` | Add a bot for Slack, Discord, Teams, Google Chat, Linear, or GitHub. |
| `nikcli bot start <name>` | Start a bot process. |
| `nikcli bot stop <name>` | Stop a running bot. |
| `nikcli bot webhook` | Configure or display webhook URLs for a bot. |
| `nikcli plugin <module>` | Install and merge a plugin module into config. Flags: `--global`, `--force`. |
| `nikcli github install` | Install the GitHub app integration. |
| `nikcli github run` | Run a GitHub automation helper. |
| `nikcli ads create` | Create a new ad entry in config. |
| `nikcli ads list` | List configured ads. |
| `nikcli ads remove <id>` | Remove an ad by ID. |
| `nikcli ads toggle <id>` | Toggle an ad on or off. |
| `nikcli ads enable <id>` | Enable a specific ad. |
| `nikcli ads disable <id>` | Disable a specific ad. |

## Models, Locale & Config

| Command | Purpose |
| --- | --- |
| `nikcli auth list` | List authenticated providers. |
| `nikcli auth login` | Authenticate with a provider. |
| `nikcli auth logout` | Revoke provider credentials. |
| `nikcli account login` | Log in to a nikcli account via device code. |
| `nikcli account logout` | Log out from the current account. |
| `nikcli account list` | List stored accounts. |
| `nikcli account switch` | Switch the active account. |
| `nikcli account orgs` | List organizations for the current account. |
| `nikcli models [provider]` | Inspect or refresh the model catalog. Flags: `--refresh`, `--verbose`. |
| `nikcli agent create` | Create a new agent definition. |
| `nikcli agent list` | List all defined agents. |
| `nikcli image-model [provider] [model]` | List or set the default image generation provider and model. |
| `nikcli speak-model [provider] [model]` | List or set the default text-to-speech provider and voice. |
| `nikcli locale [action]` | Show, set, or reset CLI language, region, and model reply language. Actions: `show` (default), `set`, `reset`. See the [Localization](/docs/localization) page. |

Terminal

bash 

```
nikcli models anthropic --refresh
      nikcli locale set --language ja --timezone Asia/Tokyo
      nikcli locale set --reply-language fr
      nikcli account login
      nikcli account switch
```

$ shell · paste into your terminal

## Diagnostics & Maintenance

| Command | Purpose |
| --- | --- |
| `nikcli doctor [--json]` | Diagnose common setup issues: version, runtime, TTY, PATH, disk, config, server. Exits non-zero on failures. |
| `nikcli heap [--detailed]` | Show heap and process memory metrics. `--detailed` (alias `-a`) shows all V8/Bun memory fields. |
| `nikcli usage` | Show token usage with charts and visual breakdowns. |
| `nikcli stats` | Show token usage and cost statistics across sessions. |
| `nikcli generate` | Generate OpenAPI specs and related assets. |
| `nikcli export [sessionID]` | Export session data as JSON. Omit the session ID to export the most recent session. |
| `nikcli import <file>` | Import session data from a JSON file or URL. |
| `nikcli upgrade [target]` | Upgrade to the latest release or a specific version target. The install method is detected automatically and the upgrade runs through it (npm, yarn, pnpm, bun, brew, choco, scoop, or the standalone installer); override it with `--method`. On Windows a standalone install cannot overwrite the binary that is running the command, so the new version is staged and swapped in once the command exits. |
| `nikcli uninstall` | Remove nikcli. Flags: `--keep-config`, `--keep-data`, `--dry-run`, `--force`. |

### OpenTelemetry (OTLP) and live telemetry

nikcli ships a small observability layer that exports Effect spans over OTLP and publishes them on the bus for the live TUI panel. See [Observability](/docs/observability) for the full reference. Quick reference:

Terminal

bash 

```
# Export to a local Jaeger collector
      OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 nikcli run "summarize this repo"

      # Disable the live panel but keep OTLP export
      OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
      NIKCLI_DISABLE_OTEL_LIVE=1 \
      nikcli serve --port 4096
```

$ shell · paste into your terminal

Terminal

bash 

```
nikcli doctor
      nikcli doctor --json
      nikcli heap --detailed
      nikcli stats
      nikcli usage
      nikcli export abc123 > session.json
      nikcli import ./session.json
      nikcli upgrade
      nikcli uninstall --keep-config --dry-run
```

$ shell · paste into your terminal

---

Source: https://nikcli-ai.dev/docs/cli