perseus

CLI

Perseus in your terminal

The same engine that powers the playground, scriptable from any agent harness. One curl | sh, one perseus login, then ask repo questions and pipe cited answers straight into Claude Code, Codex, or Cursor.

Quick install

One-line install

The script auto-installs uv if missing, then runs uv tool install perseus from the private git repo. Beta access required — the install script will halt with a friendly message if your tenant isn't cleared. Once installed, run perseus --help to confirm.

Core commands

perseus

User-facing commands for indexing + asking questions.

install
curl -fsSL https://perseus.computer/install.sh | sh

Auto-installs uv if missing, then `uv tool install perseus` from the private git repo. Beta access required - sign in at https://perseus.computer first. Python 3.11+.

login
perseus login

Opens a browser to perseus.computer/cli/login, signs you in with GitHub, then drops a tenant-scoped JWT onto a loopback port and stores it at ~/.config/perseus/token (0600).

index a local repo
perseus index /path/to/repo

Walks the tree, chunks files, builds embeddings + sparse index. Defaults to the current git repo.

check index status
perseus index --status

Shows the latest ready index id for the current repo.

list indexes
perseus indexes

Lists recent indexes visible to your tenant. --all includes prewarm/temp rows.

ask in the current repo
perseus query "where is auth enforced?"

Runs MCTS end-to-end against the latest ready index for the current git repo. Prints cited answer + evidence.

ask a specific index
perseus query <index-id> "where is auth enforced?"

Same, but pinned to a specific index id (handy when you have multiple).

open a hit in $EDITOR
perseus open <path>:<line>

Pipe a citation from `perseus query` straight into your editor.