Skip to content
Agentmine

Agent CLI contract

Agentmine is built for agents and automation. Every command follows the same contract, so a calling agent or script can rely on stable structure instead of parsing human-oriented text.

The contract

  • stdout is one JSON envelope.
  • warnings are returned in the stdout envelope’s warnings field.
  • progress goes to stderr as NDJSON.
  • errors include stable codes and retry guidance.
  • commands are non-interactive by default.
  • schema discovery is available through agentmine schema.

Error codes

Errors carry a stable code and fall into one of three ranges, each mapped to a specific process exit code:

RangeCategoryExit code
1xxxuser2
2xxxsystem3
3xxxtransient4

Transient (3xxx) errors are the ones worth an automatic retry; user (1xxx) errors mean the invocation itself needs to change; system (2xxx) errors indicate an environment or internal problem.

Progress on stderr

Progress is reported as throttled NDJSON events on stderr — for example a phase.sub event carrying current, total, and processed counts — so stdout stays reserved for the final JSON result and a long-running command (like normalize or extract over a large corpus) can still be monitored line-by-line.

An extension that fails during startup may also emit an unstructured diagnostic on stderr before the final envelope. Callers should treat only JSON objects with a progress-event shape as progress.

Corpus freshness warnings

agentmine stats returns a data.freshness snapshot for the boundary between normalized inputs and extract-owned facts. Pending sessions and changed raw workflows are tracked independently. When either still needs extraction, stats, query, and fact-backed browse commands add an EXTRACTION_PENDING warning to the normal success envelope.

This includes sessions and the default JSON form of session, whose payloads expose derived commit and subagent fields. session --md renders only normalized transcript data and does not add the warning.

The warning does not change the result rows, exit code, or status. Treat derived fact results as incomplete until agentmine extract succeeds; normalized-session commands can still be used.

Schema discovery

Run agentmine schema to inspect the result-envelope schema, exit codes, and top-level command registry. Use agentmine schema --tables to list database tables and views, or agentmine schema --table messages to inspect one table before writing ad-hoc SQL.