FAQ.
Questions, fixes and terms.
Short answers, what to do when something fails (your agent usually handles it; this is what it sees), and the words emfirge uses.
Questions
Do I need to learn the CLI?
No. Your agent uses it. You give your agent the setup prompt once and it runs every emfirge command itself. The Agent reference is written for the agent; you never have to read it.
What do I actually do?
Set up once: paste the setup prompt into your agent, approve the browser sign-in when your agent shows it, and create the read-only role with one click in AWS, then give your agent the role ARN (Set up). After that you ask your agent to change your AWS as usual and read what it hands back. You also say yes before a check that costs money, and you decide what your agent is allowed to apply.
My agent runs in the cloud or in CI, with no browser. How does it sign in?
It does not sign in. On your own computer you run npx emfirge login, then npx emfirge key create --name ci, and set the key it prints as EMFIRGE_API_KEY in your agent environment's secret settings. Your agent then uses the key and skips the browser. You still create the read-only role yourself and give your agent the role ARN. Steps are under Set up; the commands are in the Agent reference.
How do I make, list or revoke an API key?
With the CLI, on a computer where you are signed in: emfirge key create --name LABEL shows the key once; emfirge key list shows your keys (never the key itself); emfirge key revoke KEY_ID stops one at once. There is no web page for keys. A project can hold 10 active keys, and a key cannot make more keys. See Security & privacy.
Does emfirge change my AWS?
No. It is read-only. Your agent applies with its own credentials; emfirge records and verifies.
Which agents work?
Any agent that can run a shell command: Claude Code, Codex, Cursor, Gemini CLI and others. An MCP adapter exists for clients that cannot, but the npm version (0.2.3) is behind the repo and an update is coming; the CLI is the supported path today.
Which clouds?
AWS today. The core is built to be cloud-neutral, with one adapter per cloud, but only AWS exists.
Does my data go to an LLM?
Emfirge has no LLM. Identifiers are tokenized on your machine before your agent's model sees them. See Security & privacy.
Is a pass a guarantee?
No. A branch is a model of your cloud. A pass is evidence, and every verdict says what was checked and what was not.
What if emfirge cannot model my change?
It cannot pass. The change is listed as unmodeled and the verdict gets stricter. See Coverage.
Does a block stop my agent?
Only if the agent listens. Emfirge is advisory today: it does not stop anyone with their own AWS credentials.
Is it open source?
The engine is AGPL-3.0, and the MCP adapter and the CLI are Apache-2.0. Source on GitHub.
What does it cost?
Nothing while in beta. See Pricing.
Troubleshooting
emfirge is not found, or Node errors on start
Your agent needs Node.js 20 or later. npx emfirge --version prints the version that runs, and npx emfirge --help prints the commands the server offers.
Access denied or 403 when reading my account
Check the role ARN, the trusted account and the ExternalId in your stack against the link emfirge connect prints; your agent can run it again to print the link. A role made with an older shared ExternalId must be redeployed with your own. A 403 is exit code 2.
The scan is empty
Confirm the region: most resources are regional and emfirge needs one. Check that the role has the read permissions in iam-role.yaml. An empty result does not mean your account has no risks.
Branch not found
Your agent should use the exact ID printed by emfirge branch list, against the same backend that created it. This is exit code 3.
A change was rejected
The branch must be open, the resource type supported, and the target must exist for a modify or delete. Unknown fields are rejected. Check Coverage and run emfirge try again with the exact ID.
HTTP 409 on a change, rollback, discard or new branch
Someone else changed the branch: run emfirge branch get for the new revision token and pass it with --revision. Or 10 branches are already open on one base scan: discard branches you no longer need. This is exit code 5.
Timeouts or HTTP 429
A scan can take a while on a large account; the client waits up to 240 seconds. For 429 (exit code 4, rate_limited), follow the limit and reset time in the message.
Exit code 6, "needs a newer emfirge"
The server's command is newer than the install. Your agent runs npx emfirge@latest, then retries.
Your agent says it is not signed in (exit code 2)
It runs emfirge login; that opens your browser and needs you to sign in with GitHub or Google within 5 minutes. The sign-in page opens on the machine where your agent runs. If your agent runs in the cloud or CI, set EMFIRGE_API_KEY instead. A key that was revoked also gives exit code 2: run emfirge key list on your computer to check, and make a new one.
emfirge key create says forbidden (exit code 2)
It was run with a key. Only a browser sign-in can make a key, so a leaked key cannot make more. Run it on your own computer after emfirge login, with EMFIRGE_API_KEY unset.
emfirge request exits 1
It is not built yet. It prints a JSON error, not_built, and sends nothing.
The verdict says a scanner was unavailable
Native results still return. coverage_warnings says the result is not full coverage. Do not treat it as complete.
Glossary
| Term | Meaning |
|---|---|
| Branch | A base snapshot plus an ordered list of changes. An empty branch equals live. |
| Snapshot | What emfirge read from your account at one moment. The base of every branch. |
| Change | One add, modify or delete of a supported resource on a branch. |
| Context | What is true about your cloud: what exists, what is live, what depends on what, and your marks. |
| Verb | One of the six CLI commands your agent runs: context, branch, try, check, request, report. request is not built yet. |
| Check | One of six questions about a branch: data, exposure, money, availability, control, outside world. Each answers with facts, what was checked and what is unknown. |
| Unknown | What a check could not look at, and why. Unknown means not checked. It never means safe. |
| Changed setting | A setting that differs between a branch and its base, named without its value: judged by a check, or named as not judged. |
| Verdict | pass, warn or block, with reasons. Advisory evidence, not a guarantee. |
| Reason code | A stable name for one fact in a verdict, such as recently_used. |
| Lens | An evaluator that looks at the branch from one angle. Several lenses feed the six checks. |
| Law | A numbered property test the engine must always satisfy, such as L7: the same snapshot and changes give the same verdict. |
| Request | An ask to the owner, raised by an agent. Not built yet. |
| Hand-back | What emfirge report returns: the exact calls, bound by hash to the verdict they were judged with. |
| API key | A secret that starts with emf_, for an agent that cannot open a browser. You make it with emfirge key create; the agent sets it as EMFIRGE_API_KEY. |
| Token | A stand-in such as SG_001 for a real identifier, made on your machine. |
| emfirge.md | A planned plain-English file of your marks and limits. Not built yet. |
| MCP | Model Context Protocol: the interface an agent client uses to call tools. Emfirge offers it as an adapter. |