# Commands for looking into and changing code

These commands show you what your code does: its routes, the SQL its
queries send, and what a prompt sends a model.

| Command | Does |
|---|---|
| `jadpo routes` | Lists every route |
| `jadpo sql <query>`, `jadpo sql <action>` | Prints the SQL a query or an action's writes send |
| `jadpo ai show <prompt>` | Prints what a prompt sends a model |
| `jadpo ai record <prompt> --as <name>` | Records the model's answer to a prompt, for tests |
| `jadpo ai usage` | Shows the tokens and cost of the app's model calls |

## `jadpo routes`

Lists every route with its full method and path, its file, its API, its
authentication and the query or action it runs. Authentication shows
`required`, `none` or `fresh` ([Routes: signed in by
default](08-identity.md#routes-signed-in-by-default)). A connection's
generated webhook shows `signature` ([External
services](11-integrations.md)), and is listed under `webhooks  /webhooks`
when the app declares no `webhooks` API.

## `jadpo sql`

Prints the SQL a query sends to PostgreSQL: each statement, one for each
include too, with the parameters that fill it. It takes `--json`.

Given an action, it prints each `create`, `update`, `delete` and
transition the action writes, in order, with its parameters as the action
writes them. With each, it says what a refusal raises: the constraint and
the failure its `conflict:` arm names, the not-found failure, or a fault.
For a transition whose `when:` can refuse a record, it also prints the
statement that asks when no row changed.

Tab completes the project's queries and actions. Run without one, it
fails and lists them.

## `jadpo ai show` and `jadpo ai record`

`jadpo ai show <prompt>` prints what a prompt sends a model: its type,
file and version, the instructions as the system message, the
conversation's turns, and the request as the user message, with each
placeholder as the file writes it ([AI](ai.md)). It takes `--json`, and
the prompt's name or its type's. A misspelt action or prompt is
`cli.ai_arguments` with the nearest name. A prompt with errors shows them
instead.

`jadpo ai record <prompt> --as <name>` asks the configured model once, as
the prompt's first `ai.generate` call does. It uses the values of the
prompt's last `jadpo dev` call, or those of `--fixture <fixture>`. It
keeps the answer, with the prompt's version, as
`recordings/<prompt>/<name>.json` beside the prompt, its plain values
replaced by placeholders.

Through a package's connection it never asks the live service and never
uses a stand-in credential. With nothing to ask with, it is refused
(`recording.refused`). A refusal, no answer, or an answer that doesn't
decode keeps nothing (`recording.failed`).

## `jadpo ai usage`

Shows the tokens the app's `ai` calls used today and this month (UTC) and
their estimated cost, by prompt and model, against
`ai: { limits: { per_day: } }`. It reads the counts in the limits' store,
and never a prompt or an answer ([AI](ai.md)).

It takes `--json`. It shows the day's tokens, calls and cost, a table of
each prompt and model, and a footer that fails once the day's tokens are
spent. The database is the one its connection's setting names, a running
`jadpo dev`'s, or `--url`'s. One it can't read is `ai.usage_unavailable`.

Not built yet:

- `jadpo inspect`, which prints the project map: every declaration, call
  and failure. Until then `build/manifest.json` and the catalogues hold
  the map.
- `jadpo sql` for SQLite, which comes with a SQLite store, and
  `jadpo sql --explain`, which runs the statement on a disposable
  database and shows the plan. The flag says `toolchain.not_built_yet`.
- `jadpo impact <name>`, which lists what a change to `name` reaches
  ([Project layout and modules](project-layout-and-modules.md)).
- `jadpo rename <old> <new>`, which renames a declaration or field
  everywhere and keeps its stored data. It refuses a new name already in
  use.
- `jadpo domain rename`, `split` and `merge`, which move a domain's files
  and update every call
  ([Project layout and modules](project-layout-and-modules.md)).