AI Agents

AI Agents

propq is AI-agent ready by design: stable JSON output, a self-contained skill, and a single-binary install with no daemons.

The golden rule: always use --json

Agents should always pass --json for structured, parseable output:

propq --json --sql "SELECT COUNT(*) FROM users" -s local     # structured result
propq servers --json                                         # server inventory
propq --json --dry-run --sql "DROP TABLE x" -s local          # safe preflight
propq --json --csv --sql "SELECT * FROM users" -o users.csv   # export
propq --history                                               # recent queries
propq --json -s "www1|www6" --sql "SELECT version()" --stream # live streaming

JSON schema

Each element of the result array:

{
  "server": "prod-eu-1",
  "database": "shop_main",
  "status": "OK",
  "rows": { "columns": ["id"], "rows": [["1"]] },
  "affected": 0,
  "elapsed": "12.3ms"
}

• status: OK | ERR | SKIP
• rows present only for SELECTs; values are always strings
• error present only when status is ERR

Full details: Output-Formats

Install the skill

propq embeds a SKILL.md that teaches agents (Hermes, Claude Code, etc.) how to use it correctly:

propq skill install

This writes ~/.hermes/skills/software-development/propq/SKILL.md so agent tooling can discover propq and follow its conventions — including the always---json rule and the safety flags.

propq skill show      # print the embedded skill
propq skill install -u   # regenerate from the repo's source SKILL.md first

Agent checklist

1. --json on every query
2. --dry-run before anything destructive
3. --force only when the user explicitly approves a destructive statement
4. --no-confirm only when target scope is already pinned down
5. Check propq config check first if connections are failing
6. Prefer propq servers --json for inventory instead of parsing config by hand

Why this matters

• Single ~10 MB binary, no server, no daemon, no lock files
• Deterministic JSON schema stable across versions
• --dry-run + --json = side-effect-free planning
• -N / --no-output for pure status signals
• -o FILE to persist results for later processing

Next: Development