Use cf-orbs in CI or from an agent

Every command can run without a terminal. A command runs non-interactive when any of these is true:

• You pass --non-interactive.
• The environment variable CI is set.
• Standard input is not a terminal.

In that mode the CLI never prompts, so it reads secrets from the environment or from files.

Install without prompts

Put the Amp provider token in a file with mode 600, outside the project. Don’t put it on a command line that gets logged.

tok="$(mktemp)"
trap 'rm -f "$tok"' EXIT
printf '%s' "$TOKEN_FROM_SECRET_STORE" > "$tok"
npx cf-orbs init --non-interactive \
  --token-file "$tok" \
  --provider-name "<name from Amp>" \
  --subdomain "<name>" \
  --account-id "<id>"

• --subdomain is used only if the account has no workers.dev subdomain.
• --account-id is needed only if wrangler whoami lists more than one account.
• AMP_ORB_PROVIDER_TOKEN also works in place of --token-file.
• Allow 20 min for the command: use a long timeout, or run it in the background.

On success you get exit code 0, a line provider: running, and a last line amp -ox "hello from cf-orbs" --orb-provider <name>.

JSON output

With --json, a command prints one JSON document on stdout, and progress goes to stderr. For init, the result has "ok": true, url, mode, providerName, and next. On failure, the document is {"ok": false, "error": "Failed: ... — fix: ..."}.

Errors

Every error is one line: Failed: <cause> — fix: <action>. Do the action, then run the same command again. init is safe to run again.

Exit codes: 0 for success, 1 for a failure, 2 for a bad flag or an unknown command.

For a stack trace, set CF_ORBS_DEBUG=1.

For AI agents

The repo has an AGENTS.md that tells an AI agent how to install cf-orbs from a terminal. You’ll find it in the GitHub repo.

An agent should not do these things:

• Do not set "debugExec": true unless the user asks for the substrate benchmark (a platform test that needs it).
• Do not run uninstall --yes without the user’s approval.
• Do not start a second amp orb provider on the same token.
• Do not edit .cf-orbs/wrangler.jsonc.