> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getasym.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
asymmetric 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:

```bash theme={null}
asymmetric query slack-a1b2 "select count(*) from messages"
```

```
 count
-------
    20
(1 row)
```

JSON for programmatic scoring:

```bash theme={null}
asymmetric query slack-a1b2 "select id, name from channels" --json
```

```json theme={null}
[
  { "id": 1, "name": "general" },
  { "id": 2, "name": "random" }
]
```

From a file or stdin:

```bash theme={null}
asymmetric query slack-a1b2 -f ./check.sql
echo "select now()" | asymmetric query slack-a1b2
```

Deliberate write (off the default safety rail):

```bash theme={null}
asymmetric 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

```bash theme={null}
asymmetric 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

```bash theme={null}
asymmetric 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:

```bash theme={null}
asymmetric db slack-a1b2 --json
```

```json theme={null}
{
  "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:

```bash theme={null}
eval "$(asymmetric db slack-a1b2 --json | jq -r .command)"
```

### Errors you might see

| Error             | Cause                  |
| ----------------- | ---------------------- |
| `CLONE_NOT_FOUND` | No clone with that id. |