Skip to content
Atoms

CLI reference

Run the project-local executable as vendor/bin/atoms. Every command accepts --root to select the application root.

Command Purpose
init Create atoms.json and atoms-composer.json; print the pinned runtime scaffold command.
make:atom NAME Scaffold an Atom; optionally add Methods, a first migration, or WebSocket handlers.
validate Discover and statically validate the configured Atom tree.
build Produce a deterministic bundle and manifest.
diff Compare the current manifest with a saved manifest.
dev Build and run the local Worker through its installed Wrangler.
deploy Build, stage, and deploy through the installed Wrangler.
status List deployed Worker versions for an environment.
rollback [VERSION] Move a Worker to an earlier version (default: the previous one).
secrets:set KEY [VALUE] Set a secret readable by Atom code through $this->config().
secrets:list List Worker secret names for an environment.
shared-secret:set Set ATOMS_SHARED_SECRET (or, with --previous, the rotation overlap) on the Worker, read from stdin.
shared-secret:unset Remove the rotation overlap secret from the Worker, closing a rotation window.
token Print the bearer derived from ATOMS_SHARED_SECRET, for hand-issued requests.
ai:install Install or regenerate the Atoms agent guidance.

Local development

Section titled “Local development”

Initialize the project and install the Worker dependencies first, then run:

Terminal window
vendor/bin/atoms make:atom GameRoom --with-methods --with-migration
vendor/bin/atoms dev --env staging --callback-url http://127.0.0.1:8000/atoms/callback

dev builds the bundle and starts the Worker. validate checks your Atom code; build produces a bundle.

Deployment

Section titled “Deployment”

After configuring deployment:

Terminal window
vendor/bin/atoms deploy --env production
vendor/bin/atoms status --env production

To restore a selected Worker version, follow Rollback.

Command options

Section titled “Command options”
  • init — --project (defaults to the directory name), --path (defaults to app/Atoms). Refuses if atoms.json already exists. Also appends /.atoms/ and /.env.atoms.* to .gitignore, each only if absent.
  • make:atom NAME — --with-methods, --with-migration, --websocket. NAME must be a valid PHP class name.
  • validate — --json for machine-readable output.
  • build — --fast skips the vendor stage (refuses with ATOMS-E107 if atoms-composer.json declares packages); --out (defaults to .atoms/build).
  • diff — --against a saved manifest.json to compare with the current one.
  • dev — --env (required), --port (defaults to 8787), --callback-url (overrides everything else; otherwise ATOMS_CALLBACK_URL from the environment this command was started with, then from .env.atoms.<env>, then the selected environment’s callback_url), --worker-dir (defaults to atoms-worker/ beside atoms.json), --no-build to reuse the bundle already staged in the Worker project.
  • deploy — --env (required), --bundle to deploy a prebuilt bundle instead of building, --manifest (defaults to manifest.json beside --bundle), --worker-dir, --callback-url (overrides everything else; otherwise ATOMS_CALLBACK_URL from the environment this command was started with, then from .env.atoms.<env>, then the selected environment’s callback_url — the same order dev uses).
  • status, secrets:list, shared-secret:unset — --env (required), --worker-dir.
  • rollback [VERSION] — --env (required), --message/-m, --worker-dir. VERSION defaults to the previous version.
  • secrets:set KEY [VALUE] — --env (required), --worker-dir. Reads the value from stdin when the VALUE argument is omitted.
  • shared-secret:set — --env (required), --worker-dir, --previous to target ATOMS_SHARED_SECRET_PREVIOUS instead of ATOMS_SHARED_SECRET, --force to overwrite an existing value. Reads the secret from stdin. Leaves an existing secret unchanged unless you pass --force.
  • token — --worker-dir (defaults to atoms-worker/ beside atoms.json). There is no --env: the bearer is derived from ATOMS_SHARED_SECRET alone, and the Worker directory is the same for every environment.

Secrets

Section titled “Secrets”

secrets:set NAME maps application-facing names through the Worker’s configured allowlist prefix, normally ATOMS_CONFIG_; shared-secret:set and shared-secret:unset manage the authentication secret, which Atom code can never read. See Secrets and authentication for both, and for atoms token.

dev and deploy check that the runtime stamp matches the CLI’s exact release before building. See Upgrade the runtime for the upgrade command and which files it replaces.

Wrangler resolution

Section titled “Wrangler resolution”

Deployment commands use, in order:

  1. absolute ATOMS_WRANGLER_BIN;
  2. node_modules/.bin/wrangler under the selected Worker directory;
  3. a global wrangler on PATH.

Run npm ci in the Worker directory to install its pinned Wrangler version.

Credentials

Section titled “Credentials”

CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID pass directly into Wrangler’s environment and are never written to a file or a log. Both resolve in the one order — the environment the command was started with, then .env.atoms.<env> beside atoms.json, then, for the account id only, environments.<env>.account_id. There is no --account-id flag and no --api-token: a credential in argv is visible to every process on the machine. See Authenticate with Cloudflare.

This applies to every command that contacts Cloudflare, not only deploy — status, rollback, secrets:set, secrets:list, shared-secret:set and shared-secret:unset read the same two environment layers for the same two values. A .env.atoms.<env> that exists but cannot be parsed is ATOMS-E109 on any of them.

atoms status reports Worker versions. It does not report an endpoint URL from atoms.json; configure the monolith’s independent ATOMS_ENDPOINT yourself.

For data recovery limitations, see Rollback.