Install once. Begin read-only. Keep your data.

Know where operator data lives

No config file is required for a first run. State defaults to $XDG_STATE_HOME/cloudflare-fleet/state.json or ~/.local/state/cloudflare-fleet/state.json. Policy defaults to $XDG_CONFIG_HOME/cloudflare-fleet/fleet-policy.json or ~/.config/cloudflare-fleet/fleet-policy.json. Files Fleet creates are mode 0600, and the doctor warns about unsafe existing files or symbolic links.

Selection precedence is an explicit command flag, a Fleet environment variable, an XDG environment variable, then the per-user default. Fleet-specific environment paths must be absolute.

export CLOUDFLARE_FLEET_STATE_FILE="$HOME/.local/state/cloudflare-fleet/production.json"
export CLOUDFLARE_FLEET_POLICY_FILE="$HOME/.config/cloudflare-fleet/production-policy.json"
cloudflare-fleet config show

Use --state-file and --policy-file instead when a profile should apply to only one command. State contains inventory snapshots, intent, and activity. Policy contains typed operator exceptions. Neither contains the API token, but both can reveal sensitive fleet configuration and should stay private and backed up.

Use a simple daily operating loop

cloudflare-fleet doctor --live
cloudflare-fleet audit --fail-on warning
cloudflare-fleet dashboard

The dashboard is read-only until launched with --write. Use --fresh when a launch should bypass cached inventory. After a reviewed mutation, inspect durable evidence with cloudflare-fleet activity list; begin recovery only with cloudflare-fleet activity undo plan --id ACTIVITY_ID, which blocks if live state no longer matches the verified operation.

The noninteractive CLI follows the same plan and apply split. Generate a JSON plan, present it for approval, and pass its exact digest to the corresponding apply command. A changed digest exits distinctly before mutation.

Connect a trusted MCP client

The installed cloudflare-fleet mcp command is a stdio server with no network listener and no arbitrary Cloudflare API passthrough. Its first diagnostic tool, get_runtime_status, can explain missing setup before an agent attempts fleet work.

Codex

Add the server to ~/.codex/config.toml and explicitly forward the credential variables from the environment that launches Codex.

[mcp_servers.cloudflare_fleet]
command = "cloudflare-fleet"
args = ["mcp"]
env_vars = ["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"]

Run codex mcp list, then inspect /mcp in a session and ask Fleet for get_runtime_status. See the official Codex MCP guide for configuration semantics.

Claude Code

Register the command at user scope, then launch Claude Code from the shell that exports the credentials.

claude mcp add --transport stdio --scope user cloudflare-fleet -- cloudflare-fleet mcp
claude mcp list

Inspect /mcp in a session and ask Fleet for get_runtime_status. The registration stores only the command and arguments. See the official Claude Code MCP guide for scopes and environment handling.

Other clients

{
  "mcpServers": {
    "cloudflare-fleet": {
      "command": "cloudflare-fleet",
      "args": ["mcp"]
    }
  }
}

Arrange for the client process to inherit the two credentials. Append absolute --state-file and --policy-file arguments when the server should use an explicit profile. Read and plan tools work without interactive approval; apply tools require a client that supports MCP input elicitation. Use the CLI or dashboard for review and apply if the client does not present that elicitation.

Update or uninstall without losing state

Choose the desired release tag, install it over the existing package, and rerun the live doctor.

npm install --global "github:j-256/cloudflare-fleet#v0.1.0"
cloudflare-fleet --version
cloudflare-fleet doctor --live

Run npm uninstall --global cloudflare-fleet to remove only the program. npm does not remove the state and policy paths shown by cloudflare-fleet config show.

Work from a source checkout

A checkout is for development and hosted deployment. Its wrappers enter the same implementation without replacing the durable global install.

git clone https://github.com/j-256/cloudflare-fleet.git
cd cloudflare-fleet
npm ci
npm run fleet -- doctor
./launch.sh

The checkout-local launcher is also read-only by default. Run the test and publication commands in CONTRIBUTING.md before proposing a change.