query & db
Read and write a clone's database from the CLI.
These two commands let you inspect a clone's database — the primary way to score what an agent actually did.
query
hone env query <id> [sql] [options]Runs SQL against the clone's database. Read-only by default — reads are
enforced at the connection level (default_transaction_read_only=on), so a
stray UPDATE can't slip through unless you ask for it.
Arguments
| Argument | Required | Description |
|---|---|---|
<id> | yes | The clone id. |
[sql] | no | Inline SQL. Omit to read from --file or stdin. |
Options
| Option | Description |
|---|---|
--json | Output rows as a JSON array. SELECT only — can't combine with --write. |
-w, --write | Allow writes. Off by default. |
-f, --file <path> | Read SQL from a file. |
SQL source precedence: --file > inline argument > stdin.
Examples
Inline read:
hone env query slack-a1b2 "select count(*) from messages" count
-------
20
(1 row)JSON for programmatic scoring:
hone env query slack-a1b2 "select id, name from channels" --json[
{ "id": 1, "name": "general" },
{ "id": 2, "name": "random" }
]From a file or stdin:
hone env query slack-a1b2 -f ./check.sql
echo "select now()" | hone env query slack-a1b2Deliberate write (off the default safety rail):
hone env query slack-a1b2 "delete from messages where id = 5" --writeGuardrails
| Invocation | Result |
|---|---|
--json --write | Exit 2: "--json is for reads; drop --write or drop --json." |
| No SQL anywhere | Exit 2: "No SQL given. Pass it inline, with -f <file>, or via stdin." |
Errors you might see
| Error | Cause |
|---|---|
CLONE_NOT_FOUND | No clone with that id. |
CLONE_START_FAILED | Shared Postgres is down — spin a clone first — or the SQL itself failed. |
db
hone env db <id> [options]Prints the exact docker compose exec + psql command to open an interactive
shell into a clone's database (clones share one Postgres container, so the
command targets the shared postgres service and selects the clone's database
with -d). It doesn't open the shell or touch Docker — it just gives you the
command to run, so you can copy it or pipe it.
Options
| Option | Description |
|---|---|
--json | Output the connection facts as JSON. |
Examples
hone env db slack-a1b2 clone slack-a1b2 · db clone_slack_a1b2
open a shell with:
docker compose -p asym-shared -f compose.shared.yml exec postgres psql -U postgres -d clone_slack_a1b2JSON:
hone env db slack-a1b2 --json{
"id": "slack-a1b2",
"database": "clone_slack_a1b2",
"command": "docker compose -p asym-shared -f compose.shared.yml exec postgres psql -U postgres -d clone_slack_a1b2"
}Open the shell in one line:
eval "$(hone env db slack-a1b2 --json | jq -r .command)"Errors you might see
| Error | Cause |
|---|---|
CLONE_NOT_FOUND | No clone with that id. |