Fjall Docs — deploy AWS infrastructure into your own account

Fjall offers two ways for an AI agent to drive the CLI. Pick by host capability. They are not equivalent.

Two surfaces

Surface	Status	Best for
SKILL + CLI (the recipe loaded from `~/.claude/skills/fjall/SKILL.md`)	Production-ready (primary)	Claude Code, and any host that loads SKILL files
MCP server (`@fjall/mcp`)	Beta (build from source)	Claude Desktop, Cursor, Cline, Continue, Zed. Hosts that speak the Model Context Protocol but lack SKILL files

The SKILL + CLI path is what every onboarding flow ships against. The agent reads recipes from SKILL.md and shells out to fjall … subcommands, getting back TOON-formatted, exit-coded output with credentials masked by default. --agent is how the agent asks for that output, on every command that has an agent surface. The MCP server is a thin transport wrapper that exposes a subset of CLI commands as MCP tools. It exists because some hosts cannot load skill files. It is pre-1.0: end-to-end coverage is partial and the protocol-frame contract can change between betas.

Output mode

From fjall 38, --agent on the command line is the only way to get agent output, and the only input to the decision. Through 37.x the CLI inspected the machine it ran on: seventeen environment markers (CLAUDECODE, CURSOR_TRACE_ID, CODEX_SANDBOX, GEMINI_CLI, AI_AGENT and the rest) behind a TTY check. The same script emitted TOON on one host and prose on another. That inference is deleted. Without the flag no command emits agent output, on any host, whatever editor or harness you run it under. A human running Fjall inside an agent session now gets exactly the output they get in a terminal. There is no --no-agent. It went with the inference, and fjall … --no-agent now fails with an unknown-option error rather than silently doing something else. Delete it from any 37.x script. An agent or wrapper that relied on being auto-detected must pass --agent. Anything that already passed it is unaffected.

Commands that refuse the flag

Thirteen command paths have no agent surface. They refuse --agent, --budget, --fields and --full before the command runs, rather than answering with prose under a success exit code. Each refusal names what to do instead.

Command	What the refusal names
`accounts`	`fjall accounts list --output json`, a single line of strict JSON
`releases`, `services`	`fjall releases <app> --json` and `fjall services <app> --json`, the same data machine-readably
`reconnect`	Run it without the flag, then read the resulting state with `fjall connect status --agent`
`rollback`	No machine-readable output. Run it without the flag, read the exit code, then confirm the active release with `fjall releases <app> --json`
`rollout`	No machine-readable output. Run it without the flag, read the exit code, then confirm service state with `fjall services <app> --json`
`doctor`	No machine-readable output. Run it without the flag and read the diagnostics as text
`agent install-hooks`, `agent uninstall-hooks`	Run it without the flag. It reports what it changed as human text
`agent`, `deployments`, `dev`, `dev substrate`	The verb to run on a dispatcher, for example `fjall deployments list --agent`

Masked by default, with declared carve-outs

The value a command exists to hand back travels verbatim. Every other field on the same result masks as usual.

Command	Verbatim field
`fjall secrets get`	`value`
`fjall secrets export`	`content`
`fjall token create`	`token`
`fjall unlock bucket`	`capturedPolicy`, a `--fields` extra rather than a default field

A verbatim field is neither masked nor thinned by --budget. Masking one would redact nothing the caller does not already hold, and would return *** to the question the command was asked, which reads as an answer and is not one.

When to pick which

Claude Code uses SKILL. Run fjall agent install-skill to install the recipe.
Anything else uses MCP. Build the server from a checkout and register it in your client’s MCP server list. If your host later grows SKILL support, switch. The SKILL path is faster, more thoroughly tested, and gets new flows first.

SKILL + CLI quick start

# Install the recipe into your agent's config
fjall agent install-skill

# Verify the recipe was written (Claude Code default)
ls ~/.claude/skills/fjall/SKILL.md

Options

Flag	Default	Effect
`--output-dir <dir>`	`~/.claude/skills/fjall`	Write the skill bundle elsewhere. The verification path follows this flag.

The skill bundle ships with the CLI and is stamped with its version. Re-run fjall agent install-skill after every CLI upgrade: it rewrites the recipe in place and reports the version it replaced. A skill installed before fjall 38 tells the agent that destroying an unused application clears an application-limit refusal, which it never did. From fjall 38 the recipe says destroy does not clear it, and points at fjall apps deregister <app> --confirm <app>, run by an organisation owner or admin on a signed-in user credential. With the skill installed, the agent follows the plan, review, apply recipe for application scaffolding: preview with fjall apps create --dry-run --agent, review the TOON output, apply, then deploy.

Add session-start context

install-skill writes the recipe only. Ambient session context is a separate opt-in step:

fjall agent install-hooks

That adds a SessionStart entry to ~/.claude/settings.json which runs fjall agent session-context. Claude Code is the only host the installer targets today. See Session Hooks for opt-out, idempotency, and the payload shape.

MCP server quick start (beta)

@fjall/mcp is a private workspace package. It is not published to npm, and no published package installs a fjall-mcp executable. Build it from a checkout of the Fjall monorepo and point your host at the built entry point by absolute path.

Install the CLI the server shells out to

npm install -g fjall

Build the server from a checkout

Run these from the inner workspace root (<repo>/fjall/). @fjall/util provides the protocol schema and @fjall/cli is the subprocess target, so build both first.

npm run build -w @fjall/util
npm run build -w @fjall/cli
npm run build -w @fjall/mcp

For Claude Desktop, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "fjall": {
      "command": "node",
      "args": ["/absolute/path/to/fjall/mcp/build/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Restart your host

The production tools, the scaffold_from_repo prompt, and the fjall://plans/{planToken} resource scheme appear after restart.

CLI resolution

The server locates the Fjall CLI at startup in two steps, in order:

FJALL_CLI_PATH, an absolute path to cli.js.
A sibling lookup beside process.execPath, which finds a global npm install -g fjall.

If neither finds a real file, the server fails fast with FjallCliNotFound. Set FJALL_CLI_PATH when the CLI lives outside the standard global-install path:

{
  "mcpServers": {
    "fjall": {
      "command": "node",
      "args": ["/absolute/path/to/fjall/mcp/build/index.js"],
      "env": {
        "NODE_ENV": "production",
        "FJALL_CLI_PATH": "/absolute/path/to/fjall/cli/dist/src/cli.js"
      }
    }
  }
}

Production tools (MCP)

The server registers 23 production tools, plus a dev-only scaffold.protocol.echo behind FJALL_MCP_DEV=1. Every project-scoped tool takes an absolute path and spawns the CLI there, so the CLI reads that project’s fjall-config.json, active target, and organisation binding.

Scaffolding

Tool	Annotation	Purpose
`detect_app_framework`	`readOnlyHint`	Inspect a repo for type, framework, Dockerfile, and port
`plan_app_scaffold`	`readOnlyHint`	Compute a scaffold plan, returns `fjall://plans/{planToken}`
`apply_app_scaffold`	`destructiveHint`	Apply a planned scaffold and stream progress

Scaffold inputs

plan_app_scaffold refuses anything outside its declared vocabularies at the plan boundary, rather than minting a token whose apply fails in the CLI. pattern, patternTier and type derive from the same @fjall/util tuples fjall apps create reads. The rest are free-form strings or booleans, checked for shape rather than membership.

Input	Accepts
`path`, `name`	Required. Absolute path to the repo root, and the application name in kebab-case
`pattern`	`payload`, `staticsite`. The deployable set. `nextjs` is detected, never scaffolded
`patternTier`	`custom`, `lightweight`, `resilient`, `standard`
`type`	`custom`, `enterprise`, `lightweight`, `resilient`, `standard`, `tinkerer`. The CLI’s `--type`, not the pattern tier
`network`	`enterprise`, `lightweight`, `none`, `resilient`, `standard`. Narrower than the CLI’s `--network`, which also takes `tinkerer`
`database`	Boolean, mapping to the CLI’s bare `--database`
`containerPort`	Integer, 1 to 65535
`source`, `buildCommand`, `outputDir`	Required together when `pattern` is `staticsite`. The plan refuses without them
`patternDomain`	A custom domain for the application, the CLI’s `--pattern-domain`
`template`	A single-template scaffold name, the CLI’s `--template`
`dockerfile`	Path to an existing Dockerfile, relative to the repo root
`git`, `github`	Booleans, mapping to the CLI’s `--git` and `--github`
`repoVisibility`	`private`, `public`. The CLI’s `--repo-visibility`
`intent`	Free-form text, up to 1000 characters

Every CLI-facing field lands in resolvedInputs and is re-emitted on the apply argv, so apply_app_scaffold runs what the human reviewed. intent is recorded on the plan and never reaches the argv. path becomes the apply run’s --into. A host built from a 37.x checkout sent free-form strings for pattern, type and database, and a patternTier of tinkerer or enterprise. Those are rejected now.

Organisation

Tool	Annotation	Purpose
`plan_create_organisation`	`readOnlyHint`	Validate name, email, and regions, return a plan token
`apply_create_organisation`	`destructiveHint`	Scaffold the organisation CDK code and open the AWS OIDC trust flow

Resources and deployment

Tool	Annotation	Purpose
`add_resource`	`destructiveHint`	Add a `database`, `storage`, `compute`, `messaging`, `cdn`, or `network` resource
`plan_deployment`	`readOnlyHint`	Compute the resource-level change plan without mutating anything
`apply_deployment`	`destructiveHint`	Apply a planned deployment after re-checking its digest, refusing a stale plan
`destroy`	`destructiveHint`	Tear down a deployed application on AWS. Asks the host to confirm first. Applications only, tiers are CLI-only

There is no de-register tool. Freeing an application slot against the plan limit is CLI-only: fjall apps deregister <app> --confirm <app> (see fjall apps).

Confirming a destroy

destroy is irreversible and has no plan/apply pair, so consent is taken before anything is spawned. A bare call asks the host to confirm through MCP elicitation, and only a proceed: true answer reaches the CLI. The prompt names the application and the resolved project directory, because an agent that resolved a different project than the user had in mind is what the prompt exists to catch. force and skipConfirmation both default to false, and both are strict booleans: the string "false" is a validation error, not consent. force does not bypass the confirmation. It adds --force to the CLI call once the host has answered. The host gets ten minutes to put the prompt in front of a person, and a progress report from the host restarts that clock rather than counting against it. A host that cancels the request while the prompt is up gets a refusal, never a spawn. Every one of these refusals ends Nothing was destroyed.

Error code	When	Cure
`ELICITATION_REJECTED`	The user declined, the host cancelled the prompt, or the host’s answer did not match the schema	Nothing to retry. Ask the user, and call again only if they want the teardown
`ELICITATION_UNAVAILABLE`	The client cannot elicit at all: it declared no elicitation capability, or it implements no handler	Confirm the destruction with the user yourself, then call again with `skipConfirmation: true`
`ELICITATION_FAILED`	The confirmation did not complete (a timeout, a dropped transport, an unknown throw), or the request was cancelled after it	Call `destroy` again to ask once more. `skipConfirmation` is deliberately not offered here

Through 37.x force and skipConfirmation both defaulted to true, so a bare destroy call forwarded --force --skip-confirmation with nothing asked. Upgrading a checkout gives you a prompt where there was none, and a host without elicitation support gets a refusal where there was a teardown.

Regions

Tool	Annotation	Purpose
`plan_provision_region`	`readOnlyHint`	Preview adding an AWS region: affected accounts and notes
`apply_provision_region`	`destructiveHint`	Append the region to organisation config and start the deployment

Compliance remediation

Tool	Annotation	Purpose
`detect_remediations`	`readOnlyHint`	List open findings with their strategy and auto-remediable flag
`plan_remediation`	`readOnlyHint`	Prepare one finding by `issueId`, return a plan token
`apply_remediation`	`destructiveHint`	Run the remediation: open a PR, or unlock a quarantined bucket

CI setup

Tool	Annotation	Purpose
`detect_ci_setup`	`readOnlyHint`	Detect the provider, repository, and application `fjall ci setup` targets
`plan_ci_setup`	`readOnlyHint`	Validate the setup, pin the provider and application the plan run itself resolved, and return a plan token. Nothing is written until apply
`apply_ci_setup`	`destructiveHint`	Write the planned workflow file and return the web-app URL to mint at
`verify_ci_setup`	`readOnlyHint`	Dry-run the CI auth handshake, returning per-check results with fixes
`status_ci`	`readOnlyHint`	Report deploy-token counts, expiry runway, and the held credential kind

plan_ci_setup pins the provider and application its own fjall ci setup --plan run resolved, never the values you passed, because apply_ci_setup replays the stored record rather than re-detecting. It refuses with CI_SETUP_PIN_UNRESOLVED, and plans nothing, when that run reports no provider and app (the cure it names: check the project resolves under fjall ci setup --plan, then re-plan), and again when what it resolved disagrees with an explicit provider or app you asked for. force, which overwrites an existing workflow file, is a strict boolean: the string "false" is a validation error, not consent.

apply_ci_setup writes the workflow file and returns workflowPath and mintUrl. It never returns a token: POST /api/ci/tokens accepts only interactive browser sessions, so the CLI has no mint path. Mint the token in the web app as an owner or admin under Settings → CI/CD Tokens (the mintUrl the tool returns), store it as the CI secret, then run verify_ci_setup. See CI/CD Deployment.

Read-only listings

Tool	Annotation	Purpose
`list_releases`	`readOnlyHint`	List an application’s releases newest-first, the rollback targets
`list_compliance_issues`	`readOnlyHint`	List compliance findings, most severe first
`list_insights`	`readOnlyHint`	List cost, security, reliability, and performance insights

The server also registers list_resources, which is not currently usable: it invokes fjall list without an application name, and the CLI requires one. Run fjall list --app <name> in a terminal for a single application’s resources.

Fjall has no manual profile step and no fjall profile command. AWS profiles are derived in memory from your organisation config, and the active deployment account is selected with fjall target set <name>. See Understanding Profiles.

Plan, review, apply

Most write paths split into a read-only plan tool and a destructive apply tool. Agents call them in order so the host can render the intermediate plan before any writes. The detect_app_framework, plan_app_scaffold, apply_app_scaffold trio is the canonical scaffold flow. add_resource and destroy are the two exceptions. Neither has a plan tool, so there is no intermediate plan for the host to render before the write. Plan tools return a planToken valid for 15 minutes. plan_app_scaffold additionally stores the plan as an MCP resource at fjall://plans/{planToken}, where the token is an HMAC-SHA256 value bound to the plan id, its expiry, and a per-process server secret. apply_app_scaffold takes that URI as planUri. The other apply tools take the bare planToken. Both the apply tools and the resource read verify the token before any lookup:

Error code	Meaning
`INVALID_PLAN_TOKEN`	Tampered or malformed token
`EXPIRED_PLAN_TOKEN`	Past the 15-minute TTL
`STALE_PLAN`	The world changed between plan and apply
`PLAN_ALREADY_APPLIED`	The same plan was applied once already

Restarting the server invalidates outstanding plans by design.

Authentication

Both surfaces read the same token store at ~/.fjall/auth.json (or $FJALL_CONFIG_DIR/auth.json). Run fjall login once before the agent’s first call.

Surface	Missing-auth behaviour
SKILL + CLI	Resolves missing auth inline via the device-code flow. It pauses, you complete the browser step, the agent continues.
MCP server	Returns a `NOT_AUTHENTICATED` frame. Log in out-of-band, then retry. The protocol stream cannot be interrupted by interactive prompts.

Next Steps

Session Hooks

Install the hook that loads Fjall context at agent session start.

fjall login

Authenticate the CLI before the agent’s first call.

Understanding Profiles

See how AWS profiles are derived and how fjall target selects the deploy account.

fjall ci

Mint deploy tokens and wire up CI, the surface the CI setup tools drive.

Core Commands

Infrastructure Codemods

Insights

Management Commands

Build & CI

Environments & Data

Diagnostics & Recovery

Authentication

Agent Mode

Agent Mode

Two surfaces

Output mode

Commands that refuse the flag

Masked by default, with declared carve-outs

When to pick which

SKILL + CLI quick start

Options

Add session-start context

MCP server quick start (beta)

CLI resolution

Production tools (MCP)

Scaffolding

Scaffold inputs

Organisation

Resources and deployment

Confirming a destroy

Regions

Compliance remediation

CI setup

Read-only listings

Plan, review, apply

Authentication

Next Steps

Session Hooks

fjall login

Understanding Profiles

fjall ci

​Two surfaces

​Output mode

​Commands that refuse the flag

​Masked by default, with declared carve-outs

​When to pick which

​SKILL + CLI quick start

​Options

​Add session-start context

​MCP server quick start (beta)

​CLI resolution

​Production tools (MCP)

​Scaffolding

​Scaffold inputs

​Organisation

​Resources and deployment

​Confirming a destroy

​Regions

​Compliance remediation

​CI setup

​Read-only listings

​Plan, review, apply

​Authentication

​Next Steps

Session Hooks

fjall login

Understanding Profiles

fjall ci

Two surfaces

Output mode

Commands that refuse the flag

Masked by default, with declared carve-outs

When to pick which

SKILL + CLI quick start

Options

Add session-start context

MCP server quick start (beta)

CLI resolution

Production tools (MCP)

Scaffolding

Scaffold inputs

Organisation

Resources and deployment

Confirming a destroy

Regions

Compliance remediation

CI setup

Read-only listings

Plan, review, apply

Authentication

Next Steps