Skip to content
orbitpush

AI coding agents and scripts

How orbitpush behaves without a terminal, so scripts and coding agents can run it safely.

orbitpush asks nothing when it runs without a terminal: when stdin or stderr is not a terminal, or when CI is set to anything but false or 0. Every question then has to be answered by a flag, and the API key comes from BUNNY_API_KEY.

export BUNNY_API_KEY=...
npx orbitpush init --name my-site --dir dist --region DE --delivery-region EU --delivery-region US --yes
npm run build
npx orbitpush deploy
npx orbitpush domains add www.example.com   # prints the DNS record, exits 1 until it is set

Coding agents: set CI=1

Some coding agents run commands in a pseudo-terminal, where orbitpush would ask its questions and wait for an answer that never comes. Set CI=1 for them:

CI=1 npx orbitpush deploy

Then nothing asks, and domains add checks DNS once instead of waiting up to 15 minutes.

Agents can also read /llms.txt, which gives them these rules in a compact form.

Rules without a terminal

  • Commit orbitpush.json after init. Without a terminal, deploy never creates a site. It stops when the file is missing.
  • init needs --name and --dir, or --yes to take the defaults, so a guessed name never creates zones.
  • deploy, disable and enable take no input.
  • destroy needs --yes.
  • domains add checks DNS once instead of waiting, and exits with 1 while the domain is not connected. Run it again a few minutes later.
  • domains list exits with 1 while any domain is not connected, so a script can poll it.

Exit codes

Code Meaning
0 Success
1 An error, an unknown option, or a domain that is not connected yet
2 Unknown command
130 Cancelled with Ctrl+C

Errors go to stderr. An unknown option stops with 1, so a typo never falls back to a default.

Recommendations for agent instructions

If you let an agent deploy for you, tell it to:

  1. Build the project with its existing build command, and check that the output directory has index.html at its root.
  2. Run CI=1 npx orbitpush deploy when orbitpush.json exists.
  3. Otherwise ask you for the project name and regions, then run init with explicit flags.
  4. Never run destroy, disable or deploy --prune-hostnames unless you asked for it.
  5. Report the URL that deploy prints, or the exact error.