Perseus CLI quickstart

The Perseus CLI is the fastest way to connect a real checkout to Perseus. It indexes the code you are editing, including uncommitted files, and then answers questions with ranked path:line hits. Agents can call the same commands, so their repo search goes through Perseus instead of generic file exploration.

Indexing makes a repo searchable. Run it from the checkout agents will work in.

cd /path/to/your/repo
perseus index

Pass a local path to index another checkout, or pass owner/repo / a GitHub URL to index GitHub's copy server-side.

perseus index ../other-checkout
perseus index efficientsystemsinc/perseus

• --force rebuilds from scratch instead of sending an incremental delta.
• --json prints one parseable success record to stdout.
• --no-progress removes the live progress UI for CI logs.
• --approve-all installs agent rules during indexing without prompting.
• --status shows the latest ready index instead of starting a job.

Keep the index fresh

During active work, run watch once and let it sync edits in the background. Queries use the last ready index while the fresh one lands.

perseus watch

# stop after a fixed window
perseus watch --for 10m

• --no-initial waits for a file change before indexing.
• --once runs one sync decision and exits.
• --status prints watch state; use it for diagnosis, not as a readiness gate.
• --change-limit limits changed paths printed in status/change logs.
• --force syncs on startup even if watch thinks the tree is fresh.

Use query for one focused location, route, symbol, or error path. Write short noun phrases, not broad questions.

perseus query --no-summary --json "auth enforcement on query route"
perseus query --no-summary --json "PlanCheckoutButtons billing route"

Good queries name the rare thing: a route, visible UI label, function, table, error string, or command surface. Avoid one-word searches like handler, config, or service.

• --no-summary skips answer synthesis and prints ranked locations only.
• --json puts structured JSON on stdout and status on stderr.
• --files-only prints bare path:line results for piping; implies --no-summary.
• -k, --top-k raises or lowers the maximum number of hits returned.
• --index queries an explicit index id or owner/repo instead of the current checkout.
• --diff adds explicit git diff context such as main...HEAD.
• --diff-mode chooses changed, impacted, or regression search over the diff.

Use research when several different questions belong together. It returns per-question hits plus a combined reading list.

perseus research   "checkout billing route"   "pricing plan catalog"   "billing tests for plan limits"

• QUESTION... requires 2-8 distinct questions, not synonyms for one search.
• -k, --top-k sets hits per question.
• --files-only prints only the combined reading list.
• --json prints the raw packet.
• --index runs against an explicit index id or owner/repo.

Before editing a shared symbol, ask what rides on it. Before shipping a diff, ask what the diff puts at risk.

perseus impact BillingPlan --print-tests
perseus impact perseus/core/billing.py --run-tests

perseus eval --print-tests
perseus eval --run-tests
perseus eval --diff main...HEAD --print-tests

• --print-tests prints the test command(s) Perseus derives from the impact packet.
• --run-tests runs those commands and exits with the failing test status.
• --test-command overrides the test runner prefix when auto is not enough.
• --files-only prints the verify-order as path:line entries.
• --json prints the raw packet for automation.

Trace code flow

Use path when you know two endpoints and need the symbol graph between them.

perseus path post_query persist_run
perseus path routes/billing.py BillingPlan --max-depth 8

• --max-depth, -d sets the maximum hops on a path.
• --paths, -k sets how many shortest paths to return.
• --files-only prints path steps as path:line blocks.
• --json prints the raw PathResult.

These commands explain identity, inventory, and plan state. They are useful when choosing a non-current index or debugging access.

perseus status
perseus indexes -n 50
perseus billing

• status --json prints account, org, repo, branch/worktree, index, and billing state.
• indexes --json prints indexed contexts exactly as the API returns them.
• billing --json prints plan, usage, entitlement caps, and Stripe setup state.

Install the Perseus skill for coding agents. It teaches them to use Perseus commands for repo search instead of harness-wide file exploration.

npx skills add efficientsystemsinc/perseus-skill

perseus rules add and perseus update run this for you (and clean up the old built-in skill). If npx is missing they offer to install Node.js on the spot, so a manual install is rarely needed.

For repository-local rules, use perseus rules.

perseus rules add
perseus rules status
perseus rules update
perseus rules remove

Send feedback when retrieval helped, missed, looked stale, or when CLI output/docs were confusing. Traces are optional.

perseus feedback --agent "top hit nailed it - BillingPlan was in perseus/core/billing.py"
perseus feedback --agent "docs gap: query flags need clearer examples"

• --agent tags source=agent and links the latest local Perseus session when one exists.
• --metadata, -m adds key=value metadata; repeat for multiple fields.
• --trace-file attaches a trace file after user approval.
• --send-trace confirms trace upload without an interactive prompt.

Use perseus --help or man perseus for the terminal reference. The common commands are: