Agentero CLI

Agentero CLI

Role

You use the agentero CLI as a stable machine interface to an Agentero vault. The CLI is not a chat runtime: no BYOA, no ACP, no paper-reader. Reading and writing lecture-style NOTES.md is your job (or use the separate paper-reader skill / desktop Zap workflow).

Prerequisites

• Binary name: agentero (POSIX). Desktop: 设置 → 关于 → 安装 CLI writes the ~/.local/bin/agentero symlink. If missing from PATH, say so and fall back to reading Vault files directly; do not invent catalog rows.
• Prefer always passing --json (disables interactive prompts). JSON is a compact single line; --pretty pretty-prints for humans (avoid in tool loops).
• Destructive deletes: pass -y / --yes under --json / non-TTY.
• Vault resolution (first wins): --vault <path> → env AGENTERO_VAULT → cwd walk-up (.agentero/catalog.sqlite). When cwd is already the vault, do not start with vault list.

Command discovery

Use describe only when you do not already know the flags:

agentero describe --json              # curated op index
agentero describe paper.list --json   # one op: input/output/errors/examples
agentero <group> --help               # human clap help

Do not invent subcommands. There is no agentero graph. Do not pair describe with every list/get call.

Hard boundaries

Progressive disclosure

1. L0 — AGENTS.md (if present; usually already in context)
2. L1 — only when discovering the collection: agentero paper list --json (default rows: id/path/title; add --fields / --full only if needed)
3. L2 — {paper}/NOTES.md when the user asks about a known paper
4. L2.5 — agentero layout list <paper> / agentero mark * (CLI writes mark JSON)
5. L3 — {paper}/PAPER.md (if no TeX)
6. L4 — {paper}/source/** (TeX preferred when present)

Skip levels you do not need. A known paper path does not require paper list or vault list first.

Task protocols (pick one)

Known paper path (QA / summary / short claim) — prefer files; CLI only if you need catalog fields the files lack:

# optional metadata:
agentero paper get papers/<shelf>/<id> --json
# then read NOTES.md → (TeX | PAPER.md) as needed

Explore / list the collection:

agentero paper list --json

Import / download / parse / tag:

agentero import id <arxiv|doi|url> --json
agentero paper download papers/<…> --json
agentero paper parse papers/<…> --json
agentero paper tag add papers/<…> "label:color" --json

Layout / marks — paper path is required:

agentero layout list papers/<…> --json
agentero layout list papers/<…> --kind figure --json
agentero mark list papers/<…> --json

After a paper-reader / explicit “mark as read” workflow only:

agentero paper set-read papers/<…> --json

Do not run set-read after ordinary Q&A or summary that did not finish NOTES.

JSON contract

• Success: { "ok": true, "data": … } on stdout (compact; --pretty indents).
• Failure: non-zero exit + { "ok": false, "error": { "code", "message", "details" } }.
• Stdout = result; stderr = progress/diagnostics. Parse error.code when retrying.

Path / id resolution

• Prefer Vault-relative path (e.g. papers/nlp/1706.03762).
• Bare id may hit paper_ambiguous when the same id exists under multiple shelves — retry immediately with a path from error.details.candidates.
• Prefer path from the user / @ mention / prior paper list row; do not probe with bare id when a path is already known.

Invariants

• On mark_locate_failed, retry with a longer verbatim quote — never guess coordinates.
• On layout_index_missing, ask the user to open the paper in Agentero and run Figures analysis — do not invent bboxes.
• Keep Obsidian wikilinks [[...]] when you edit Markdown.
• Never invent catalog metadata; trust CLI / files.
• Prefer short tool loops: the fewest CLI/file reads that answer the question.

Activation notes

Depending on the agent: Codex $agentero-cli, Claude /agentero-cli, Pi /skill:agentero-cli, others follow this body directly.