Petavue CLI (@petavue/cli)

Agent-native CLI for the Petavue recommendations engine — review and act on your recommendations from the terminal, or let your AI agent (Claude Code, Codex, …) do it for you.

Install

npm install -g @petavue/cli        # or zero-install: npx @petavue/cli

Requires Node ≥ 20. No dependencies, no install scripts.

Login

Grab your API key from Petavue, then:

petavue login          # paste the key when prompted
petavue whoami         # confirms who you are

Use

petavue recs list                                  # today's open recommendations
petavue recs show <rec_id>                         # one rec as a readable briefing
petavue recs act <rec_id> --comment "what you did"     # = Accept
petavue recs reject <rec_id> --reason "why it's wrong"
petavue recs dismiss <rec_id> --reason "revisit next week"   # = Snooze
petavue recs comment <rec_id> "note for the next check-in"
petavue goals list / goals show <goal_id>

Append --json to any command for the full server payload; -q for bare ids. Exit codes: 0 ok · 1 network · 2 usage · 3 auth (petavue login) · 4 not found · 5 rejected by server.

Workflow Sessions

Create a session that mounts all your workflows, ask questions about the data, and download files — designed for AI agents to explore Petavue data programmatically.

# Create a session (mounts all your workflows read-only)
petavue session create

# Ask a question (async — returns a request id)
petavue session ask <session_id> "what were last month's top deals?"

# Poll for the answer (--wait blocks until done, --timeout N sets max seconds)
petavue session response <request_id> --wait
petavue session response <request_id> --wait --timeout 120

# Explain how an answer was built (data sources, steps)
petavue session how <request_id> --wait

# Deep link to a file in the Petavue web UI
petavue session view <session_id> <file_path>

# Download a file (returns a 15-min presigned S3 URL)
petavue session download <session_id> <file_path>

Download supports CSV, JSON, MD, TXT, PNG, JPG, PDF, XLSX, and Parquet files directly. HTML files (dashboards) are rendered to PNG via a screenshot service before download — the URL points to the screenshot, not raw HTML.

# Typical agent workflow
SID=$(petavue session create -q)
RID=$(petavue session ask $SID "what were last month's top deals?" -q)
petavue session response $RID --wait
URL=$(petavue session download $SID my_workflows/.../data/deals.csv)
curl -o deals.csv "$URL"

# Deep link for the human to view in-browser
petavue session view $SID my_workflows/.../output/dashboard/index.html

Let your agent drive it

petavue skill install

Installs the Petavue skill into every agent harness found on your machine — Claude Code and Codex today, both using the same open SKILL.md standard. Run it once, from anywhere: it links to the file inside the installed package, so npm update -g @petavue/cli keeps the skill in step with the CLI.

petavue skill install --claude      # or --codex — pick one explicitly
petavue skill install --project     # into the current repo instead of your home dir
petavue skill install --copy        # copy instead of link (re-run it after upgrades)

Then ask your agent things like "check my Petavue recommendations and brief me" — the bundled SKILL.md teaches it the commands, the etiquette (mandatory comments, never inventing reasons), and when to reach for --json. Safe to re-run any time; it repairs a stale or broken install.