CLI Reference

Top-level commands

These are the top-level commands implemented by the AgentPM CLI. Global flags can be passed before the command: --root, --url or --service-url, --read-url, and --org-code.

agentpm [--root DIR] [--url URL|--service-url URL] [--read-url URL] [--org-code CODE] COMMAND

Conversation commands

The conv family gives read-only access to visible conversation history. Add --json when scripting or when exact fields matter. The conversations alias is supported for the same command family.

agentpm conv [search|show|find|insights|project|tree|projects|work|git|trajectory|viewer]

Search syntax

Conversation search uses the same syntax in the CLI and the UI search boxes. Search accepts plain text, quoted phrases, and structured key:value facets in one query.

• Known facets: owner, user, agent, agent_id, agent-id, model, project, cwd, source, file, content, tool, tool_type, tool_location, tool_mutability, tool_privilege, tool_status, git_cmd, git_pr, git_pr_num, git_commit, git_branch, git_remote, tag, subagent, auxiliary, and is.
• Truthy/falsey filters work for subagent and auxiliary: subagent:true, subagent:false, auxiliary:true, auxiliary:false. is:subagent and is:auxiliary are also supported.
• file: and cwd: support substring matching and simple wildcards. An explicit file: filter is exclusionary: conversations with no file evidence do not match.
• Exact conversation ids are special-cased. Searching for a single goc_... id resolves that conversation directly.

Search examples

These same query strings can be used in the product UI where conversation search is available. In the UI, day:YYYY-MM-DD maps to the date filter; in the CLI, use --date, --start, or --end.

agentpm conv search 'project:agentpm file:frontend/lib/docs-content.ts cli reference' --limit 10
agentpm conv search 'tool:Bash tool_mutability:mutating unsafe command' --json
agentpm conv search 'git_pr_num:73 git_branch:feat/homepage-v2-refresh'
agentpm conv search '"broker unavailable" user:@will project:thalosx'
agentpm conv search --start 2026-06-01 --end 2026-06-30 'content:image daily digest'

JSON output and conversation search shape

Use --json when another tool or agent needs stable fields. Conversation search returns the query, page controls, total count, and a list of conversation summaries with top matches.

agentpm conv search --json --limit 5 'project:agentpm file:frontend/app docs'

{
  "ok": true,
  "agent_id": "agt_...",
  "orgs": ["agentpm"],
  "query": "project:agentpm file:frontend/app docs",
  "total": 12,
  "offset": 0,
  "limit": 5,
  "has_more": true,
  "conversations": [
    {
      "id": "goc_...",
      "org": "agentpm",
      "title": "Refresh CLI reference and docs search syntax",
      "agent": "codex",
      "model": "gpt-5",
      "project": "-Users-bestomerwill-Documents-src-AgentPM",
      "cwd": "/Users/bestomerwill/Documents/src/AgentPM",
      "snippet": "Updated CLI reference...",
      "first_seen": "2026-07-10T07:40:00Z",
      "last_seen": "2026-07-10T08:10:00Z",
      "turns": 86,
      "tokens": 128000,
      "read_scope": "local",
      "top_matches": [
        { "turn_index": 42, "role": "assistant", "excerpt": "..." }
      ]
    }
  ]
}

Common examples