CLI Reference

All nestor-sh commands, organized by purpose. Run npx nestor-sh <command> --help for full per-command flag listings. The CLI binary is named nestor-sh (not nestor) to avoid clashing with other tools — npx nestor-sh works without installation.

Setup & lifecycle

Command	Purpose
`install`	Interactive setup wizard for Nestor (provider keys, ports, data dir)
`doctor`	Run health checks on the Nestor installation
`config`	Manage Nestor configuration file (get/set/show)
`start`	Start the Nestor server (Studio + API)
`daemon`	Manage the Nestor background daemon (start/stop/status)
`studio`	Manage the Studio web UI (open/status/build)

`install`

Interactive wizard that creates $NESTOR_HOME/config.json, prompts for at least one LLM provider key, validates each key with a probe call, runs initial DB migrations, and prints next steps. Idempotent — re-running upgrades the schema and adds new providers.

npx nestor-sh install
npx nestor-sh install --config ./preset.json --yes   # non-interactive
npx nestor-sh install --skip-validate                 # skip key probes

`doctor`

Diagnostic dump: Node version, pnpm version, native binding status, DB integrity, port availability, provider key reachability. Always include this in bug reports.

npx nestor-sh doctor
npx nestor-sh doctor --json    # machine-readable

`config`

npx nestor-sh config show
npx nestor-sh config get budgets.perRunUsd
npx nestor-sh config set approval.mode manual
npx nestor-sh config edit                 # open in $EDITOR

`start`

Start the API server (port 3101 by default) and Studio dashboard (port 3100). Foreground process. Ctrl-C stops cleanly.

npx nestor-sh start
npx nestor-sh start --prewarm                     # pre-warm SQLite WAL
NESTOR_STUDIO_PORT=3200 npx nestor-sh start       # custom port

`daemon`

npx nestor-sh daemon start
npx nestor-sh daemon stop
npx nestor-sh daemon status
npx nestor-sh daemon logs --tail 100

`studio`

npx nestor-sh studio open       # open dashboard in default browser
npx nestor-sh studio status
npx nestor-sh studio build      # rebuild static assets

Agents & runs

Command	Purpose
`agent`	Manage AI agents (create/list/config/delete)
`shell`	Interactive REPL with slash commands, multi-turn memory, multiline editing
`loop`	Run an agent in a fresh-context loop until a spec is met (Ralph pattern)
`test`	Run skill and agent test suites

`agent`

npx nestor-sh agent create --name coder --adapter claude --model claude-sonnet-4-6
npx nestor-sh agent list
npx nestor-sh agent config coder
npx nestor-sh agent config coder --budget-per-run-usd 1.00 --approve smart
npx nestor-sh agent delete <name>

`shell`

The most-used command. Drops you into an interactive REPL with the active agent. Slash commands cover plan/undo, pair-programming mode, conversation export, model switching, history navigation, etc.

npx nestor-sh shell
npx nestor-sh shell --agent coder
npx nestor-sh shell --agent coder --model gpt-4o
npx nestor-sh shell --hat osint              # OSINT investigator persona
npx nestor-sh shell --fresh                  # skip stored history/memory
npx nestor-sh shell --max-iterations 30

Inside the shell, type /help for the slash command catalog (24 commands including /plan, /undo, /pair, /replay, /export, /handoffs, /prompt).

`loop`

Runs the agent in a fresh-context iteration until validators (tests, linters) pass. Implements the Ralph pattern (Re-prompt And Loop with Progressive Hints).

npx nestor-sh loop --validate "Build the auth module"
npx nestor-sh loop --validate "All tests pass" --max-iterations 5

`test`

npx nestor-sh test
npx nestor-sh test --file tests/my-skill.test.yaml
npx nestor-sh test --verbose --reporter junit

Orchestration

Command	Purpose
`workflow`	Manage and run DAG workflows
`schedule`	Cron-based agent scheduling
`template`	Export/import agent configurations as templates

`workflow`

npx nestor-sh workflow run code-review.yaml
npx nestor-sh workflow list
npx nestor-sh workflow run my.yaml --param env=staging

`schedule`

npx nestor-sh schedule add --agent coder --cron "0 9 * * *" --task "review yesterday's PRs"
npx nestor-sh schedule list
npx nestor-sh schedule pause <id>
npx nestor-sh schedule remove <id>

`template`

npx nestor-sh template export coder > coder.template.json
npx nestor-sh template import ./coder.template.json --as my-coder

Integrations

Command	Purpose
`mcp`	Manage the MCP (Model Context Protocol) server
`messaging`	Discord, Slack, Telegram bridges
`skill`	Manage agent skills (install, list, translate)
`rag`	RAG (Retrieval-Augmented Generation) commands

`mcp`

npx nestor-sh mcp                    # start MCP server on stdio
npx nestor-sh mcp --debug            # with verbose logging
npx nestor-sh mcp tools              # list 15 nestor_* tools

Add to ~/.config/claude/mcp.json:

{
  "mcpServers": {
    "nestor": { "command": "npx", "args": ["nestor-sh", "mcp"] }
  }
}

`messaging`

npx nestor-sh messaging discord setup
npx nestor-sh messaging slack setup
npx nestor-sh messaging telegram setup

`skill`

npx nestor-sh skill list
npx nestor-sh skill install ./my-skill.zip
npx nestor-sh skill translate ./langchain-tool.py   # LangChain → Nestor
npx nestor-sh skill translate ./openai-fn.json      # OpenAI FC → Nestor

`rag`

npx nestor-sh rag index ./docs/                 # index a directory
npx nestor-sh rag search "deployment process"
npx nestor-sh rag stats

Observability

Command	Purpose
`watch`	Live monitor dashboard for agent activity
`telemetry`	Manage anonymous telemetry (opt-in)
`memory`	Inspect and prune agent memories

`watch`

npx nestor-sh watch                   # live terminal dashboard
npx nestor-sh watch --agent coder     # filter to one agent

`telemetry`

npx nestor-sh telemetry status
npx nestor-sh telemetry compact         # VACUUM SQLite DB
npx nestor-sh telemetry prune --older-than 30d
npx nestor-sh telemetry export --format jsonl > traces.jsonl

`memory`

npx nestor-sh memory list --agent coder
npx nestor-sh memory show <id>
npx nestor-sh memory prune --older-than 30d
npx nestor-sh memory export --agent coder > memories.json

Advanced

Command	Purpose
`evolve`	Manage skill evolution candidates (self-improving tools)
`guardrail`	Configure custom guardrail rules
`sandbox`	Manage sandbox execution backends (Docker, SSH, local)

`evolve`

npx nestor-sh evolve list
npx nestor-sh evolve approve <candidate-id>
npx nestor-sh evolve reject <candidate-id>

`guardrail`

npx nestor-sh guardrail list
npx nestor-sh guardrail add ./rules/no-rm-rf.yaml
npx nestor-sh guardrail test ./rules/no-rm-rf.yaml

`sandbox`

npx nestor-sh sandbox list
npx nestor-sh sandbox add docker --image debian:slim
npx nestor-sh sandbox use ssh-runner

Global flags

Available on every command:

Flag	Effect
`--help` / `-h`	Show command help and exit
`--version` / `-V`	Print CLI version and exit
`--data-dir <path>`	Override `$NESTOR_HOME` for this run
`--log-level <level>`	`error` \| `warn` \| `info` \| `debug` \| `trace`
`--no-color`	Disable ANSI colors (CI mode)
`--json`	Where supported, emit machine-readable JSON instead of human output

Exit codes

Code	Meaning
`0`	Success
`1`	Generic error
`2`	Invalid arguments / config
`10`	Budget exhausted
`11`	Approval denied
`12`	Validator failed (loop / test)
`13`	Provider error (rate limit, auth)
`130`	Interrupted (Ctrl-C)

✎ Edit this page on GitHub · Last updated 2026-04-26