query & db

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-a1b2

Deliberate write (off the default safety rail):

hone env query slack-a1b2 "delete from messages where id = 5" --write

Guardrails

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_a1b2

JSON:

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.

Get started

Concepts

Guides

Templates

Reference

CLI reference

query

Arguments

Options

Examples

Guardrails

Errors you might see

db

Options

Examples

Errors you might see

​query

​Arguments

​Options

​Examples

​Guardrails

​Errors you might see

​db

​Options

​Examples

​Errors you might see

query

Arguments

Options

Examples

Guardrails

Errors you might see

db

Options

Examples

Errors you might see