@golden-frijoles/cli

Create a feature flag in every environment, roll it out, and kill it — from a terminal, or from an agent. No browser, no human click.

npx @golden-frijoles/cli --version

The one-minute version

Run frijoles setup in an interactive terminal for the Golden Frijoles welcome and guided defaults. Use --no-motion or FRIJOLES_NO_MOTION=1 for a still welcome. --yes --json remains suitable for scripts.

npm i -g @golden-frijoles/cli          # or use npx for everything below

frijoles login                                # opens your browser to sign this machine in
frijoles init                                 # project + key + .env.local + the snippet
frijoles flags create checkout.demo_enabled --kill-switch --all-envs
frijoles flags rollout checkout.demo_enabled --env production --percent 25
frijoles flags kill checkout.demo_enabled --env production

Why this exists

Every high-risk change ships behind a flag, and a flag is invisible until it exists in the provider. Before this, the one line of a release that most needs to be reliable — create the flag in every environment — was the line that stopped and waited for someone to open a browser.

frijoles flags create … --all-envs is that line.

Signing in

At a terminal, frijoles login opens your browser: confirm the code it shows and this machine is signed in.

frijoles login                # browser sign-in
frijoles whoami               # who you are, which credential, which projects

Without a browser, mint a token at /app/setup/cli and pipe it in (echo "$TOKEN" | frijoles login); a piped or pasted token is read from stdin, never from argv or your history. --token <token> also works, but it lands in argv and your shell history, so prefer the pipe.

In CI, set GOLDEN_FRIJOLES_TOKEN and skip frijoles login entirely. Nothing is written to disk on that path.

A token signs you in as you: it can do exactly what your console session can do, across every project you are a member of, and nothing more. Revoke it at /app/setup/cli.

Polarity — the thing to get right

A flag's polarity decides what it serves the day it is born, and the CLI derives everything else from it, so the wrong combination is not expressible:

| You type | Default variant | Every environment serves | Reach for it when | |---|---|---|---| | --kill-switch | on | true | it is on until you kill it | | --enablement | off | false | you will open it deliberately later |

Both polarities activate in every environment you name. "Created disabled" means serving false, not absent — a flag that is not activated is missing from the snapshot, so your app falls back to its own literal and the flag is invisible in the provider, which is the failure this tool exists to end.

--all-envs, and what happens when one fails

Three environments, three writes, no transaction. So:

• each environment is written idempotently,
• you get a per-environment report, and
• the exit code is 5 if any environment failed.

Never a silent partial.

--json everywhere

Every command takes --json. Under it, stdout carries exactly one JSON document and nothing else — no progress lines, no warnings. A failure is a JSON document too, on stdout, with a stable code:

{ "ok": false, "code": "not_found", "error": "No project `acme` is available to this account." }

--help output and these envelopes are pinned by golden-file tests. They do not change on a copy edit.

Sending a North Star: frijoles north-star set

The North Star chapter of the strategy skill (Golden Frijoles plugin) leaves Roadmap/00-strategy/north-star.md, with the metric and its inputs in one ```json block under ## Sync payload. This command sends that block to your project:

frijoles north-star set Roadmap/00-strategy/north-star.md          # dry run: shows what would change, sends nothing
frijoles north-star set Roadmap/00-strategy/north-star.md --yes    # sends it once (project owners only)

A sync never replaces or deletes. A new metric key is added beside an existing North Star, and an input key that already exists moves to this metric. The dry run says so before anything is sent, and to revise a North Star you reuse its key. The server validates the block and prints its issues on a 400. A file that still has the template's <…> placeholders is refused before anything is sent.

Reading a result: frijoles north-star readings, frijoles experiments decision

An agent reading an epic's result (the plugin's epic-read) fetches the number itself through these two reads. Any project member can run them; --json prints the body the agent parses.

frijoles north-star readings grounded_bets_share --to 2026-11-04 --json   # the input's readings; `latest` is the number
frijoles experiments decision smart-defaults --json                        # the experiment's decision record

latest is the last reading on or before --to; an input with no reading yet says so rather than reporting zero. Cite them as north-star:<input>@<latest.date> and ab:<experiment>.

Exit codes

| Code | Name | Means | |---|---|---| | 0 | ok | it worked | | 1 | usage | the command is wrong — nothing was sent | | 2 | auth | the credential is not accepted — run frijoles login | | 3 | not-found | no such thing, or not yours | | 4 | conflict | someone else changed it — re-read and retry | | 5 | partial | some environments changed and some did not | | 6 | server | the server or the network is unwell — retry |

When something is wrong

frijoles doctor

It runs without a credential — diagnosing a missing one is the point — and reports every check it could run: the credentials file, the credential, its shape, whether the deployment answers, whether it accepts you, whether your active project is reachable, and whether this CLI is current. It never prints key material.

Then one line per module (Plan, Build, Ship, Measure, Spend, Operate): configured, not configured (with the command that fixes it) or could not look. Module lines never change the exit code.

Settings: frijoles setup and frijoles config

frijoles setup                                   # two questions, each with a default; --yes takes them all
frijoles config list                             # every setting, and which file it came from
frijoles config get review.reviewScope
frijoles config set review.reviewScope every-pr

Settings live in the project's golden-frijoles.config.json, the same file the Golden Frijoles skills read and write: these verbs use the config core that ships in @golden-frijoles/kit, so there is one set of rules. set refuses anything that looks like a secret (keep those in .env.local), and legacy files such as review-config.json are read but never edited. None of these verbs needs a credential.

Environment

| Variable | What it does | |---|---| | GOLDEN_FRIJOLES_TOKEN | a CLI token; wins over the saved credential. The CI path. | | GOLDEN_FRIJOLES_URL | the deployment to talk to | | GOLDEN_FRIJOLES_PROJECT | the active project |

frijoles init writes GOLDEN_FRIJOLES_URL, GOLDEN_FRIJOLES_FLAG_READ_KEY and GOLDEN_FRIJOLES_ENVIRONMENT into .env.local (mode 0600), adds that file to .gitignore — or refuses — and prints the @golden-frijoles/sdk snippet that reads exactly those names.

What it deliberately does not do

• Send events. That is the SDK's path (@golden-frijoles/sdk), and a second one would be a parallel pipeline.
• Experiments, journeys, north star, scenarios, destinations, breakers. Out of v1 on purpose.
• A TUI. Plain output and --json.
• Plans and quotas. Every account is unlimited today; frijoles will learn about plans when there is a plan to learn about.