Documentation

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

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

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

Missions

A Mission 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

Loops

A Loop 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

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

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

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

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