# `jadpo dev`

Run the app and reload on every save.

Run the application in the interpreter and serve its routes on a local port (3000 unless --port says otherwise). Each save is checked again, and once it checks cleanly the new version serves the next request; while a save has errors, the last good version keeps serving. Each request is one line, with its request id. The database is the one --url names, or else a disposable PostgreSQL started for the session; pending migrations are applied as they appear. With --no-run it only checks on every save and writes build/. An app that signs in with external_token gets a local issuer in place of the configured one, and `jadpo dev token <user-id>`, beside a running session, prints a bearer token from it for that user.

```text
jadpo dev [action] [user-id]
```

## Arguments

- `action` (optional): token, to print a bearer token for a user, or nothing to serve
- `user-id` (optional): The user's id, for token

## Flags

- `--port <port>`: Listen on this port; 0 picks a free one
- `--url <url>`: Use this database, not a disposable one
- `--no-run`: Only check on every save; serve nothing
- `--fake <connection>`: Fake this connection for this session
- `--sandbox <operation>`: Let this operation through to its sandbox

## On every command

- `--json`: Print data for tools instead of text
- `--full`: Show everything a report shortens
- `--help`: Show every flag, with examples
- `--color <when>`: Choose when to use colour

`jadpo dev --json` writes one JSON document to standard output instead of text, with the same exit code. The document has `schemaVersion`, `command` (`"dev"`), `ok`, `data` (what the command produced, `null` when it failed) and `diagnostics` (each error with its `rule`, `reason`, `next` and `help`). A command that needs a terminal refuses `--json` and names the flags that do the same job.

## Examples

```text
# Serve the project you are in on http://localhost:3000
jadpo dev
# Serve it on another port, with your own database
jadpo dev --port 8080 --url postgresql://localhost/app_dev
# Print each request as a line of data for tools
jadpo dev --json
# Call the running app as a user, with a token from its local issuer
curl -H "Authorization: Bearer $(jadpo dev token <user-id>)" localhost:3000/me
```

## Errors

- [`cli.dev_arguments`](/docs/errors/cli.dev_arguments.md): A `jadpo dev` command names an action it doesn't have, `token` without a user's id, or a `--url` the project's several stores can't share
- [`cli.dev_port_invalid`](/docs/errors/cli.dev_port_invalid.md): A `jadpo dev --port` flag holds something other than a whole number from 0 to 65535
- [`cli.dev_start_failed`](/docs/errors/cli.dev_start_failed.md): The app couldn't start under `jadpo dev`, usually because another program is using its port, it has no database to run on, or a connection would call a provider's live API
- [`migration.apply_failed`](/docs/errors/migration.apply_failed.md): Applying the project's migrations to a database stopped at a step that failed
- [`migration.drop_not_accepted`](/docs/errors/migration.drop_not_accepted.md): A migration removes data, and no acceptance in the project says a person agreed to it
- [`migration.extension_missing`](/docs/errors/migration.extension_missing.md): The project's migrations need a PostgreSQL extension, such as pgvector, that the database server doesn't offer or that the role applying them can't create
- [`migration.extension_outdated`](/docs/errors/migration.extension_outdated.md): The database server's PostgreSQL extension, such as pgvector, is older than the project's migrations and queries need
- [`migration.store_diverged`](/docs/errors/migration.store_diverged.md): The migrations a database has applied don't match the project's: one has changed since it ran, the project doesn't have one, or one comes out of order
- [`toolchain.project_not_found`](/docs/errors/toolchain.project_not_found.md): You ran a command that works on a project in a folder with no `app.jadpo`, in it or in any folder above it