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.
Get JSON instead of text
Add --json to any command:
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, now1) andok(trueorfalse). Branch onok. - A refusal has
ok: false, anerrorwith the whole message, andhints: 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.
{ "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 <key file>for the SSH key), for one command;--box <name>, a server saved earlier;- or
foxden connect user@hostonce, 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 <command> --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.envreads every answer from a file ofFOXDEN_*=valuelines (FOXDEN_PRODUCTS=…,FOXDEN_DOMAIN=…, one per line).--env-file -reads the same from stdin.foxden config import <file>sets many settings at once fromKEY=valuelines;-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
#!/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
fiConnect 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.