AI Agents and the CLI

bifurc agent init, exit codes, sessions, policy guardrails, approvals and locks for AI coding agents.

AI Agents and the Command Line

The bifurc command talks to the same engine as the desktop app, and starts one if none is running. From 0.6 it is designed to be driven by AI coding agents as much as by people and CI: short output, clear exit codes, sessions of their own, and guardrails you set.

Teach an agent the CLI

bifurc agent init

adds a short cheat sheet to AGENTS.md or CLAUDE.md in your repository: how to wait for a service, send a saved request, read captured traffic and check mocks, with the mappings and mocks of your workspace.

The same verbs are available as an MCP server:

bifurc --mcp

Output and exit codes

A request prints one summary line, such as 201 Created · 142ms · 4.2KB json · tests 3/3 ✓, and only shows the body when asked (--body, --select, --out) or when something failed. --json gives the full result.

Exit code	Meaning
0	OK
1	It ran, but a test, expectation or check failed
2	Usage: unknown option, bad argument, ambiguous name, or an item locked by someone else
3	The named item was not found
4	Network error: refused, DNS, timeout
5	No engine could be started or reached
6	Needs a person: a sealed vault with no terminal, or a call held for approval
7	Blocked by the workspace policy

Useful commands for agents:

bifurc wait http://api.localhost/health
bifurc requests send "Create order" --expect-status 201 --select .id
bifurc curl -X POST http://api.localhost/orders -d '{"items":2}'
bifurc capture list --status 5xx --last 10
bifurc changes --since 5m
bifurc setup --accept-terms --accept-privacy --workspace "Acme API"

bifurc setup finishes the first-run setup without the desktop app, for a CI machine or a fresh container.

Sessions

Without a session, the CLI shares the desktop app's cookie jar and selected environment. With --session <name> (or BIFURC_SESSION), an agent gets its own cookies, runtime variables and environment, so two agents logged in as different users do not trip over each other.

bifurc --session checkout-agent requests send "Login"
bifurc --session checkout-agent session show

Guardrails: policy and approvals

A workspace can hold a policy.yaml that limits what the command line and MCP may send. Only a person edits it; no command writes it. The desktop app shows it under Config, in Agent policy.

policies:
  - name: no-prod-writes
    deny: { env: prod, methods: [DELETE, PUT, PATCH, POST] }
  - name: local-only
    allow_hosts: ["*.localhost", localhost, 127.0.0.1]
  - name: staging-deletes
    require_human: { env: staging, methods: [DELETE] }

A denied call exits 7 with the name of the policy that blocked it. A require_human call waits: the app's footer shows an approvals badge, and its dialog lets you approve or deny each held call. You can also decide from a terminal with bifurc approvals approve or deny.

bifurc policy show
bifurc policy check DELETE https://api.staging.acme.dev/orders/1

Locks

While a session edits a request, mock, flow or environment, it holds a claim on it: others can still read and send it, but not change or delete it. The app shows a lock on claimed items, and a banner with Take over in the editor. The app claims what you edit, so an agent cannot change it under you either. A claim lasts 30 minutes unless it is renewed or released.

bifurc claim request "Create order"
bifurc claims
bifurc claim --release request "Create order"

bifurc changes lists what other sessions changed since you last asked, and a write is refused if someone else changed the item since you read it.