--- url: https://docs.codefox.ai/connect/cli-scripting.md --- # Script the foxden command line This page lets you drive the `foxden` command line from a script, a CI job or a coding agent: one JSON document per command, exit codes to branch on, and no questions that wait for a keypress. Every command is listed in [foxden command line](/reference/cli). ## Get JSON instead of text Add `--json` to any command: ```bash foxden status --json ``` * stdout holds exactly one JSON document. Everything meant for a person (progress, notes, warnings) goes to stderr. * Every document has `v` (the format's version, now `1`) and `ok` (`true` or `false`). Branch on `ok`. * A refusal has `ok: false`, an `error` with the whole message, and `hints`: the commands to run next, the first one recommended. The same message is printed on stderr, so a script that logs stderr never sees silence. ```json { "v": 1, "ok": false, "error": "foxden email: ...", "hints": ["foxden email set ..."] } ``` `foxden logs --follow` is the one exception: a followed log is a stream, so `--json` with `--follow` is refused. `foxden logs` without `--follow` returns a document like every other command. ## Exit codes | Code | Meaning | |---|---| | `0` | It worked. | | `1` | It ran and failed: a check failed, or an update's health check did not pass. | | `2` | The command was wrong, or it needs a confirmation (`--yes`) or a value (a flag). | | `3` | The server is not ready. Nothing was touched, and a hint names the fix. | | `130` | Cancelled. | Use the exit code to stop a script, and `ok` with `error` and `hints` to decide what to do next. ## Run without questions | Flag | Environment | Does | |---|---|---| | `--non-interactive` | | Never asks. A question with no answer is refused, naming the flag that gives it. A pipe, CI or `--json` turn it on. | | `--yes`, `-y` | | Answers every "are you sure?" with yes. Values are still asked for (and refused under `--non-interactive`). | | `--recommended` | `FOXDEN_RECOMMENDED=1` | Takes the recommended answer to every question that has one. | | `--quiet` | | No progress or receipts on stderr; results and errors stay. | | `--agent` | `FOXDEN_AGENT=1` | `--json`, `--non-interactive` and `--quiet` together. | | `--no-color` | `NO_COLOR` | No colour. | | `--debug` | `FOXDEN_DEBUG=1` | Shows each command `foxden` runs, its exit code and its time. | | `--offline` | `FOXDEN_OFFLINE=1` | Skips anything that reaches the network. | `--agent` never implies `--yes`. A change that needs confirming is refused with `needsConfirmation: true` and the plan, so a script or agent can show it to a person and run the command again with `--yes` once they agree. ## Pick the server A command that acts on a server needs to know which one: * `--host user@host` (with `--identity ` for the SSH key), for one command; * `--box `, a server saved earlier; * or `foxden connect user@host` once, after which every server command runs there. `foxden --agent` (with no command) prints a JSON guide to every command: its name, whether it runs on the server or on this machine, and a summary. `foxden help --json` returns one command's usage. ## Keep secrets off the command line Anything on the command line can be read from the process list, so `foxden` never takes a secret as a flag value: * A secret's flag names a file that holds it, such as `--registry-token-file`. * `foxden init --non-interactive --env-file install.env` reads every answer from a file of `FOXDEN_*=value` lines (`FOXDEN_PRODUCTS=…`, `FOXDEN_DOMAIN=…`, one per line). `--env-file -` reads the same from stdin. * `foxden config import ` sets many settings at once from `KEY=value` lines; `-` reads stdin. When an unattended install is missing an answer, it stops with exit code 2 and its document lists each missing answer's flag and environment name. ## An example ```bash #!/usr/bin/env bash set -u out=$(foxden checkup --host deploy@box.example.com --agent) if [ "$(jq -r .ok <<<"$out")" != "true" ]; then jq -r '.error' <<<"$out" >&2 jq -r '.hints[]?' <<<"$out" >&2 exit 1 fi ``` ## Connect assistants from a script `foxden mcp install` adds Foxden to an assistant on this machine (Claude Code by default; `--client` picks Claude Desktop, Cursor, OpenCode, Codex, a comma list, or `auto` for every one found). `--origin https://admin.example.com` names Admin's address when this machine is not the server Admin runs on. `--dry-run` prints what it would do, and `foxden mcp status --json` reports what each assistant holds. See [Connect your AI assistant](/connect/ai-assistant).