Perseus CLI quickstart

The Perseus CLI connects a checkout to Perseus. It indexes the code you are editing, including uncommitted files, and answers questions with ranked path:linehits. Coding agents can call the same commands.

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 JSON success record.
• --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 "auth enforcement on query route"
perseus query "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.

• --answer adds an answer grounded in the retrieved code.
• --json prints the structured result as JSON.
• --files-only prints only path:line values.
• -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 research packet as JSON.
• --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 impact packet as JSON.

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 path result as JSON.

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

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: