# Automation and agents

Use the [MCP server](./mcp.md) to expose Remote Config tools to an MCP-compatible
AI application. For agents and scripts running one-shot CLI commands, follow
the workflow below and add `--json` to each call. Commands then return one
versioned JSON envelope instead of terminal tables, colors, diffs, or prompts.

The stateful examples assume you have already configured a profile through the
[manual CLI setup path](/guide/index.md#manual-cli-setup). The guided `fbrcm setup`
command is intentionally interactive and is not available in JSON mode.

## Discover the installed binary

Do not hard-code an assumed command set. Ask the binary what it supports:

```sh
fbrcm capabilities --json
fbrcm capabilities project import --json
fbrcm schema list --json
```

Capability records describe arguments, flags, schemas, side effects,
interaction, and support for stateless, dry-run, draft, and plan execution.

## Read before writing

Resolve the exact target and inspect current state first:

```sh
fbrcm projects list --json
fbrcm get feature_enabled --project '=example-project-id' --json
```

Use exact selectors in automation. A fuzzy name that is convenient at a
terminal can become ambiguous as projects are added.

## Preview and prepare for review

When a capability reports dry-run support, validate the real candidate without
publishing it:

```sh
fbrcm update feature_enabled \
  --project '=example-project-id' \
  --type boolean \
  --value true \
  --dry-run \
  --json
```

Use a draft while several edits still need to be composed or revised:

```sh
fbrcm update feature_enabled \
  --project '=example-project-id' \
  --type boolean \
  --value true \
  --draft \
  --json

fbrcm draft diff example-project-id --against current --json
```

Use a plan when an agent must hand off one exact, validated candidate for
approval or later execution. A plan can be created directly by a supported
mutation or from a draft:

```sh
fbrcm draft publish example-project-id \
  --plan-out release.fbrcm-plan.json \
  --json

fbrcm plan validate release.fbrcm-plan.json --json
fbrcm plan show release.fbrcm-plan.json --json
fbrcm apply release.fbrcm-plan.json --dry-run --yes --json
fbrcm apply release.fbrcm-plan.json --yes --json
```

Plan creation fetches fresh bases, validates the exact changed candidates, and
runs effective trusted pre-publish hooks without publishing. Apply accepts only
targets that still match the recorded base or already match the candidate. It
does not recalculate the change. Treat the plan file as sensitive because it
contains complete base and candidate templates. See [Plans](/cli/plans.md) for
integrity, concurrency, stateless, cleanup, and retry behavior.

`--yes` authorizes a documented confirmation. It does not disable Firebase
validation, make a retry safe, or turn a destructive action into an authorized
one.

## Handle results structurally

Inspect all of these together:

- envelope `outcome` and `exit_code`;
- top-level `errors` and `warnings`;
- each `data.items[].status` in a batch result; and
- structured remediation `strategy` and `argv`.

Never branch on human-readable `message` wording. A successful diff with
changes uses status 1, and a batch can partially succeed with status 12.
Earlier successful targets are not rolled back after another target fails.

## Interaction never blocks JSON mode

JSON mode never opens a prompt, editor, file picker, or browser. If an operation
needs human input, fbrcm returns an `interaction.required` problem with status 10.
Show that request to a human, or retry only after the caller explicitly
supplies the required choice.

## Run without local state

Supported commands can operate from a short-lived access token:

```sh
GOOGLE_CLOUD_QUOTA_PROJECT=example-quota-project-id \
FBRCM_GOOGLE_ACCESS_TOKEN="$(gcloud auth application-default print-access-token)" \
  fbrcm --stateless get feature_enabled \
  --project '=example-project-id' \
  --json
```

Stateless mode skips fbrcm-managed profiles, project registrations, caches,
drafts, and hooks. It still permits explicit caller-selected input and output
files, including publication plans. A stateless plan must later be applied
with `--stateless`. fbrcm keeps the token in memory and never writes it. The
token's principal needs `serviceusage.services.use` on
`example-quota-project-id` and Remote Config access on `example-project-id`.
Check `supports.stateless` in the capability record before running a command
this way.

Continue with the [JSON contract](./json-contract.md) for the envelope, exit
statuses, schemas, and artifact results.