Skip to content

CLI

Run navi-agent --help for the complete option list. The commands below are the stable entry points for normal operation.

Agent sessions

navi-agent
navi-agent "Explain the runtime event flow"
navi-agent --session-id SESSION_ID
navi-agent --user-id USER_ID
Option Description
--session-id ID Continue a specific session
--user-id ID Select the local user identity; defaults to local-user
--system-prompt TEXT Override the default system prompt
--add-dir PATH Allow an additional workspace root; repeatable
-y, --yolo Auto-approve supported host operations without adding isolation

Setup and diagnostics

navi-agent init
navi-agent doctor
navi-agent doctor --doctor-gateway weixin

Gateway

navi-agent gateway start
navi-agent gateway send "Hello"
navi-agent gateway send "Hello" --to-user-id USER_ID
navi-agent gateway dead-letters
navi-agent gateway retry-dead-letter OUTBOX_ID

See Gateway for access policies and pairing.

Scheduled tasks

navi-agent cron run
navi-agent cron start --cron-poll-interval 60

cron run performs one scheduler tick. cron start keeps polling until it is stopped.

Evaluations

Install optional evaluation dependencies, then run an Inspect suite:

uv sync --extra eval
uv run navi-agent eval run general-qa
uv run navi-agent eval run bfcl --limit 5

SWE-bench requires its dedicated extra:

uv sync --extra swe-bench
uv run navi-agent eval run swe-bench-verified --limit 1

Skill candidates

Import a human-authored or external Skill package without activating it:

navi-agent skill import PATH --source-kind human
navi-agent skill import PATH --source-kind external

Evaluate the returned draft ID and activate it only after the A/B gate passes:

navi-agent skill eval DRAFT_ID --case-file cases.json
navi-agent skill feedback DRAFT_ID --report-path REPORT_DIR --feedback-file feedback.json
navi-agent skill aggregate DRAFT_ID
navi-agent skill activate DRAFT_ID

The case file uses a deliberately small format:

{
  "cases": [
    {
      "id": "review-readme",
      "prompt": "Review README.md and cite verified findings.",
      "required_output_terms": ["verified"]
    }
  ]
}

Evaluation writes run.json, REPORT.md, and a self-contained REVIEW.html. The viewer can download human judgments as feedback.json; skill feedback validates and persists them as immutable evidence. Feeding that evidence into an automated revision loop remains intentionally outside activation. See Skill A/B Evaluation Walkthrough for a concrete internal-comms experiment using frozen Navi Agent scenarios.

Local Trace Viewer

navi-agent trace serve
navi-agent trace render TRACE_ID

The server is read-only and binds to 127.0.0.1. See Local Trace Viewer for Skill fields, security boundaries, and single-file output options.