Set up.
What you do, once.

1. Paste the prompt

Give this to your agent. It runs every command and reads the reference written for it.

Set up emfirge for my AWS account and use it for every AWS change from now on.
emfirge is a CLI. Run it as `npx -y emfirge <command>` (Node.js 20 or later). Run `npx -y emfirge guide` first; the full reference is https://emfirge.cloud/cli.md.

1. Run `login`. It opens my browser so I can sign in with GitHub or Google. If it does not open, show me the address it prints, then wait for me.
2. Run `connect` and show me the link it prints. I will create the read-only role and send you the role ARN. Ask me which AWS region to use.
3. Run `context --refresh --role-arn ARN --region REGION`, then `context inventory`. Keep the role ARN: later steps need it.

Before any AWS change: open a branch (`branch open`), try the change on it (`try`), and read `check`. Never apply a change that did not pass. If it fails, fix your plan and try again on the branch. Ask me before `check --policy` or `check --evidence`: they cost money. When a change passes, apply it with your own access, run `report`, and tell me what changed.

Copy it, or open it in Claude, ChatGPT or Cursor with the arrow. Your agent needs to be able to run commands on your machine (Claude Code, Codex, Cursor's agent, Gemini CLI): a plain chat window cannot run npx. It needs Node.js 20 or later. If your client prefers MCP, see the MCP adapter.

The prompt points your agent to the full reference at /cli.md, the same page as CLI reference. You do not need to read it.

2. Approve sign-in

Your agent shows you a link. You sign in with GitHub or Google.

Your agent runs emfirge login. That opens your browser to a sign-in page served on your own machine, where you choose GitHub or Google. If the browser does not open, your agent shows you the address to open. You have 5 minutes. The session is kept in ~/.emfirge/credentials.json on your machine, so your agent does not need you again unless the sign-in expires.

The sign-in page lives on the machine where the command runs, so your browser and your agent must be on the same machine. If your agent runs somewhere you cannot open a browser for it, such as a cloud session or CI, use an API key (below).

If your agent runs in the cloud or CI

A cloud agent session or a CI job cannot finish emfirge login. Give it an API key for your project instead. You make the key once, on your own computer, which has a browser:

npx emfirge login                   # approve the sign-in in your browser
npx emfirge key create --name ci    # prints a key that starts with emf_, once

• Copy the key now. It is shown once and cannot be shown again.
• Set it as EMFIRGE_API_KEY in the secret settings of the place your agent runs. Never paste it into a chat or commit it. Run key create in your own terminal, so the key does not pass through a chat.
• Your agent then runs npx -y emfirge ... with no login: where EMFIRGE_API_KEY is set, emfirge uses it and skips the browser.
• You still do step 3 yourself: create the read-only role in your AWS console and give your agent the role ARN and region. A key does not create it.
• npx emfirge key list shows your keys (never the key itself). npx emfirge key revoke KEY_ID stops one at once. A project can hold 10 active keys.

A key works for your whole emfirge project, the same as your sign-in, except that it cannot make more keys: key create works only after a browser sign-in. Treat a key like a password.

Emfirge never asks for your AWS access keys. The only thing it holds that can reach your account is the role in step 3.

3. Create the read-only role

One click in AWS, then give your agent the role ARN. The role can read your account's configuration and nothing else.

Your agent runs emfirge connect and shows you a link. It opens the CloudFormation console with the template already filled in, including an ExternalId that is unique to you. You do this part because it is your AWS account: emfirge has no access to it until the role exists.

• Open the link. Read the template if you like.
• Tick the IAM acknowledgement and click Create stack. It takes about 30 seconds.
• When the stack says CREATE_COMPLETE, open its Outputs tab and copy the RoleArn.
• Paste the RoleArn to your agent and tell it which AWS region to look at. Your agent asks if you forget.

connect does not find the role by itself, so your agent needs the ARN from you. It then takes the first scan with it. A scan can take 30 to 60 seconds on a real account. Scans are limited per AWS account per day; your agent sees how many remain.

What the role can do

It carries AWS's managed SecurityAudit policy plus a short list of extra read actions: CloudWatch metrics (for usage evidence), IAM Access Analyzer policy checks, and a handful of List, Describe and Get calls. It lists secret names; it has no permission to read their values. The full list is iam-role.yaml, and a summary is on Security & privacy.

What it cannot do

It has no write permission of any kind. It cannot create, change or delete a resource, read S3 object contents, or read a secret's value.

Revoking it

Delete the CloudFormation stack. The role disappears and access ends immediately. Removing emfirge from your machine does not remove the role, so delete the stack too.

4. Done: ask as usual

Ask your agent to change your AWS the way you always do. It handles the rest.

Before it touches anything real, your agent opens a branch, tries the change on it, checks it and fixes its own plan until the check is clean. Then it applies the change with its own AWS access and tells you what it did. Emfirge never applies anything.

From here you do two things. You read what your agent hands back, and you decide. Your agent should also ask you before a check that costs money (IAM Access Analyzer policy checks, and reads of CloudTrail and CloudWatch use): those show an estimate first and run only after you agree.

Emfirge is advisory today. It does not stop an agent that has its own AWS credentials, so the prompt tells your agent never to apply a change that did not pass.

What you'll see

A short message from your agent, with the facts emfirge gave it.

Here your agent was asked to open SSH to the world on a security group. It tried that on a branch first.

I tried opening SSH (port 22) to 0.0.0.0/0 on SG_001 on a branch first.
emfirge says: block.
  introduced_critical_finding    SG_001
  introduced_critical_exposure   EC2_001
  exposure: EC2_001 newly exposed on tcp 22 from 0.0.0.0/0
  not checked (so not safe): observed traffic, host firewalls
I did not apply it. I changed my plan, opened a new branch and checked again.

When a change passes, your agent applies it and runs emfirge report. The hand-back ties the exact calls it applied to the verdict they were judged with:

{
  "kind": "aws-api-calls",
  "calls": [ { "change_index": 0, "service": "ec2", "operation": "AuthorizeSecurityGroupIngress", … }, … ],
  "input_sha256": "3c467190…",
  "verdict": "warn",
  "verdict_id": "f7dc5a85…",
  "verification": { "ok": true, "verdict": "warn", "verdict_id": "f7dc5a85…" }
}

Names appear as tokens such as SG_001 and EC2_001, because privacy defaults to strict: your agent's model never sees the real identifiers. The map from token to name stays in ~/.emfirge/tokens.json on your machine. A finding is not an error: a block still exits 0, and your agent reads it as a fact about its plan.

Without an agent

npx emfirge --help
npx emfirge login      # sign in with GitHub or Google in your browser
npx emfirge connect    # print the link that creates the read-only role

emfirge context --refresh --role-arn arn:aws:iam::123456789012:role/EmfirgeReadOnlyRole --region us-east-1
emfirge context inventory

emfirge branch open --analysis ANALYSIS_ID --name first-try
emfirge try BRANCH_ID --aws-cli "aws ec2 authorize-security-group-ingress --group-id SG_001 --protocol tcp --port 22 --cidr 0.0.0.0/0"
emfirge check BRANCH_ID --human

Next steps

• How it works: the loop your agent runs, the six checks and the record.
• Coverage: which resources a branch can change today.
• Security & privacy: exactly what the role, the engine and your machine hold.
• FAQ: do I need to learn the CLI, and what do I actually do.
• CLI reference: the reference your agent reads.