Skip to content

usage.md

Latest commit

 

History

History
269 lines (209 loc) · 10.2 KB

usage.md

File metadata and controls

269 lines (209 loc) · 10.2 KB

Usage

The full command reference for the prosa CLI. For install, see install.md. For the server + panel deployment, see self-hosting.md.

First-time setup

prosa setup

A short wizard:

  1. Server URL (default https://prosa.c3.do; configurable).
  2. Browser-based PKCE auth (opens the panel authorize URL; click Authorize this device; the CLI captures the callback on localhost).
  3. Detection of local agent histories (~/.claude/projects, ~/.codex/sessions, ~/.cursor/, ~/.gemini/, ~/.gemini/antigravity-cli/conversations/).
  4. Scheduled sync install (LaunchAgent on macOS, systemd user timer on Linux). Default interval: 15 minutes.
  5. The first scan (opt-in; you can skip it and run prosa sync later).

Flags:

Flag Default Notes
--server <URL> $PROSA_SERVER_URL or https://prosa.c3.do The server to register with.
--interval <duration> 15m How often the scheduled job runs.
--skip-scan Skip the first scan after setup.
--non-interactive Fail rather than prompt. Useful in scripts.

If you only want re-authentication, use prosa login instead of the full wizard.

Daily flow

Show the timeline

prosa                       # last 7 days, scoped to the current project if known
prosa --all                 # every project
prosa --last 30d            # broader window
prosa --last 12h --device laptop

Output is grouped by relative day (Today, Yesterday, 2 days ago, …) and shows for each session:

  • start time (with * if the session is currently active),
  • device,
  • agent,
  • project,
  • the first user prompt (truncated to fit),
  • duration,
  • main tools used.

Inside a known project, prosa auto-scopes to that project; --all overrides.

Search across turns

prosa search "sqlite FTS"
prosa search "deploy" --last 30d --project mz-iac
prosa search "deploy" --remote        # cross-device, via the server

Local search uses SQLite's FTS5 (porter + unicode61). --remote uses the server's Postgres tsvector (simple tokenizer) — useful when you want to search across machines.

Read a session

prosa show <session-id>                          # rendered (TTY) / raw (pipe)
prosa show <session-id> --json                   # one JSON object
prosa show <session-id> --raw                    # preserved JSONL bytes
prosa show <session-id> --remote --raw           # preserved bytes from server
prosa show <session-id> --max-output-lines 20    # cap per-turn body
prosa show <session-id> --remote                 # fetch from prosa-server

In a TTY the default shows the structured human view — session metadata then a turns section with chat lines and projected tool results (rendered as tool:<name>). --json emits a single {session, tools, turns} object. --raw (including with --remote) and any non-TTY pipe without --json emit the preserved JSONL bytes verbatim — the agent's source is never altered.

Sync

prosa sync                          # ad-hoc; same job the scheduler runs
prosa sync --verbose                # progress detail
prosa sync --json                   # NDJSON per session + a final summary

In interactive mode prosa sync shows a Bubble Tea spinner with progress per importer. In a pipe or under a cron-style scheduler it falls back to a quiet, structured log.

With --json, sync writes NDJSON to stdout: one {"type":"session","phase":"local|catchup","agent","session_id","status":"imported|skipped|error","push":"sent|skipped|failed|unavailable|disabled|deferred","err"} record per session, then one {"type":"summary",…} record with the run tally. Diagnostics stay on stderr.

Analytics

prosa analytics sessions            # count by agent + total turns
prosa analytics tools               # top 20 tools across the window
prosa analytics models              # session distribution by model
prosa analytics projects            # sessions per project, grouped by agent
prosa analytics profiles            # sessions per device + agent + profile
prosa analytics heatmap             # trailing 53 weeks; ignores --last/--since/--between
prosa analytics usage               # token totals + estimated USD cost
prosa analytics errors              # sessions matching error heuristics
prosa analytics hours               # sessions per UTC hour of day (00-23)
prosa analytics usage_by_model      # token totals + estimated USD cost, by model
prosa analytics errors_by_model     # flagged sessions by model (same heuristic as errors)
prosa analytics subagents           # subagent fan-out per parent agent

--remote runs the report against the server. All reports honor the global filters below, including --last, --since, --between, --project, --agent, --device, --profile, and --all. Exception: heatmap has a fixed trailing 53-week window and rejects --last, --since, and --between.

Profiles (per-agent locations)

A profile is a named location for an agent on this device — e.g. a second CODEX_HOME for another account. Every agent has a default profile; add more so sync imports from extra directories. The <path> is the agent's home directory (the importer appends its own subdir, e.g. sessions for Codex).

prosa profiles list                            # configured profiles + session counts
prosa profiles add codex work ~/.codex-work    # scan ~/.codex-work/sessions as profile "work"
prosa profiles set-path codex work ~/.codex-2  # repoint an existing profile
prosa profiles remove codex work               # stop scanning it (keeps imported sessions)

Profiles are stored in the local profiles.json (under the prosa config dir); each imported session records its profile name, so prosa --profile work and prosa analytics profiles work both locally and against the server.

Devices (cross-device)

prosa devices list
prosa devices rename <id|self> <friendly-name>
prosa devices revoke <id|self>

The local store only knows about this machine; prosa devices always queries the server.

Schedule control

prosa schedule install --interval 15m
prosa schedule status
prosa schedule uninstall

On macOS this writes a LaunchAgent plist into ~/Library/LaunchAgents/. On Linux it writes a user systemd timer into ~/.config/systemd/user/.

Global flags

Available across all commands (and as defaults for prosa with no subcommand):

Flag Default Notes
--last <duration> 7d Rolling window. Accepts 12h, 7d, 30d, etc.
--since <YYYY-MM-DD> Anchored lower bound in UTC.
--between <A..B> Closed UTC range. Both ends YYYY-MM-DD, separated by ...
--project <name> Convenience substring filter. Matches project_path, project_remote, or project_marker — so --project movaincentivo finds sessions captured under any of the three. Because this is substring matching, large stores should prefer cwd auto-scoping when possible; auto-scoping uses exact project identity filters.
--device <name> Match friendly_name (cross-device only).
--agent <name> One of claude-code, codex, cursor, gemini, antigravity, hermes.
--profile <name> Match sessions.profile exactly (e.g. default, work).
--all Drop the auto cwd-based project scoping.
--remote Query the server instead of the local store.
--json NDJSON output, one record per line.
--no-color Suppress ANSI even on a TTY.
--help Per-command help.

The bare prosa timeline accepts --limit N to cap the number of returned sessions (useful for agents that want a small sample). prosa search has its own --limit, and also honors prosa --limit N search <query> for consistency. When both are present, the local search flag wins. Other subcommands don't take one.

--last, --since, and --between are mutually exclusive — pick one. Combining them surfaces an error before the store is touched.

--json writes machine-readable NDJSON to stdout. Human logs (project scoping, progress messages) go to stderr so pipelines stay clean.

Output modes

prosa renders for three audiences:

  • TTY (default in a terminal) — styled tables, day headings, color with purpose. See cli/rendering-contract.md for the full token palette and truncation rules.
  • Plain (when stdout is redirected) — no ANSI, no day grouping repeats, no spinners. Safe for cron, scripts, pagers.
  • JSON (--json) — NDJSON, one session/result per line, stable schema per command.

Logs that aren't part of the command's primary output go to stderr — including project scope hints ("scoped to prosa · use --all for every project").

Environment variables

Variable Default Notes
PROSA_HOME ~/.local/share/prosa Data root (store + raw).
PROSA_SERVER_URL https://prosa.c3.do Server for --remote and sync.
PROSA_CONFIG_HOME ~/.config/prosa Auth token + setup state.
XDG_DATA_HOME Honored for PROSA_HOME if set.
XDG_CONFIG_HOME Honored for PROSA_CONFIG_HOME if set.
NO_COLOR Standard. Forces plain output.

Examples

A few common one-liners:

# what did I do yesterday (rolling window)
prosa --last 1d

# what did I do across Q1 2026
prosa --between 2026-01-01..2026-03-31

# everything since the V3 release tag
prosa --since 2026-05-30

# all my SQLite work, regardless of device
prosa search "sqlite" --remote --last 90d

# everything I did on mz-iac with codex (--project scopes; --all is for the
# opposite case: ignore the cwd auto-filter and show every project)
prosa --project mz-iac --agent codex

# pipe to jq
prosa --last 30d --json | jq '[.[] | {agent, project, started_at}]'

# show the raw of the most recent session
prosa --last 1d --json \
  | head -1 | jq -r '.id' \
  | xargs prosa show

Where this maps to code