# JSON output and scripting

The CLI is designed to be used by people at a terminal, but the same commands work just as well inside shell scripts, CI pipelines, and other automation. This page collects the flags that matter when you're scripting.

## Machine-readable output

A handful of commands can emit JSON instead of human-readable text. Use the global `--output` flag (`-o` for short):

```sh
dina apps list --output json
dina apps info --app my-app -o json
dina apps deployments --app my-app -o json
dina auth status -o json
dina users list -o json
```

The JSON shape is stable enough for scripts. If you need more commands to support JSON, [tell us](/docs/feedback).

Commands that don't expose a JSON form just emit plain text no matter what `-o` you pass.

## Global flags for automation

These work on every command:

| Flag | What it does |
|---|---|
| `--no-input` | Error out instead of waiting on a prompt. Use in scripts and CI. |
| `--quiet`, `-q` | Suppress informational messages on stderr. Results still go to stdout. |
| `--output`, `-o` | `text` (default) or `json`. JSON output is to stdout. |
| `--no-color` | Strip ANSI colour codes from output. Also honoured automatically when stdout isn't a TTY, or when `NO_COLOR=1` is set. |
| `--debug` | Print verbose request/response output. Also triggered by `DEBUG=1`. Useful when something's broken. |

A CI-friendly deploy looks like:

```sh
dina deploy --app my-app --tag $IMAGE --wait --no-input --quiet
```

- `--wait` makes the command exit non-zero if the deployment fails.
- `--no-input` bails if any command somehow tries to prompt.
- `--quiet` keeps CI logs tidy.

## Exit codes

The CLI returns `0` on success and a non-zero code on error. Specifically:

- Authentication or API errors → non-zero.
- Validation errors (missing flags, bad values) → non-zero, with `cobra` printing usage.
- Deploy with `--wait` that lands in a failure state → non-zero.

For one-off scripts, that's usually enough. The error message itself is prefixed with `error:` on stderr, so it's easy to grep out in logs.

## Parsing output with `jq`

```sh
# Print just the URLs of your apps
dina apps list -o json | jq -r '.[].url'

# Get the ID of the most recent deployment
dina apps deployments --app my-app -o json | jq -r '.[0].id'
```

## Signalling "not authenticated" in scripts

If a script only runs when you're signed in, check authentication first:

```sh
if ! dina auth status -o json | jq -e '.authenticated' > /dev/null; then
  echo "Not signed in. Run: dina auth login"
  exit 1
fi
```

## Keeping secrets out of shells

When passing secrets on the command line, be careful about shell history. A safer pattern is to read values from a file or environment variable in your CI, rather than inline:

```sh
dina apps env set --app my-app STRIPE_SECRET_KEY="$STRIPE_SECRET_KEY"
```

Most CI systems redact variable values from logs automatically — inline `KEY=value` literals usually aren't redacted.