Skip to content
Markdown
GuideForOperatorWith or without Foxden Admin

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:

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 ​

CodeMeaning
0It worked.
1It ran and failed: a check failed, or an update's health check did not pass.
2The command was wrong, or it needs a confirmation (--yes) or a value (a flag).
3The server is not ready. Nothing was touched, and a hint names the fix.
130Cancelled.

Use the exit code to stop a script, and ok with error and hints to decide what to do next.

Run without questions ​

FlagEnvironmentDoes
--non-interactiveNever asks. A question with no answer is refused, naming the flag that gives it. A pipe, CI or --json turn it on.
--yes, -yAnswers every "are you sure?" with yes. Values are still asked for (and refused under --non-interactive).
--recommendedFOXDEN_RECOMMENDED=1Takes the recommended answer to every question that has one.
--quietNo progress or receipts on stderr; results and errors stay.
--agentFOXDEN_AGENT=1--json, --non-interactive and --quiet together.
--no-colorNO_COLORNo colour.
--debugFOXDEN_DEBUG=1Shows each command foxden runs, its exit code and its time.
--offlineFOXDEN_OFFLINE=1Skips 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@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 <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.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 <file> 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.

Foxden is open source under Apache-2.0.