---
title: "Use cf-orbs in CI or from an agent"
description: "Run init and the other commands without prompts, with secrets kept out of the command line."
---

> Documentation Index
> Fetch the complete documentation index at: https://cf-orbs-site.mdick85.workers.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```sh
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](https://github.com/meirdick/cf-orbs/blob/main/AGENTS.md).

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`.

Source: https://cf-orbs-site.mdick85.workers.dev/docs/guides/automate/index.mdx