Skip to main content
fjall migrate runs one-off migrations that bring deployed stacks onto current fjall contracts. It has one subcommand, identity.
This command does not run database or schema migrations. Application database migrations run as part of a deploy, and fjall deploy --skip-migrations controls them.
fjall migrate identity pins the capacity identity of a deployed pre-6.0 application into fjall-config.json, so later synths reproduce the deployed resource names byte-for-byte and a rename-safe deploy stays rename-safe.
  • The Fjall CLI installed and signed in. Run fjall login first, the command authenticates before it does any work.
  • A connected AWS account holding the deployed stacks. Connect one with fjall connect.
  • An application with an infrastructure.ts, created by fjall create application.
  • A shell in the fjall project root, so the CLI can detect application targets. Without --app, a single detected application is used, and several require you to name one.
  • An account and region that map to a configured deploy target. Check with fjall target list. Pins are keyed by target name, so a session that matches no target cannot write them.

​
Pin deployed capacity identity

Pin the sole application detected in the current project:
Pin a named application:
Resolve credentials through a specific deploy target, the same way fjall deploy --target does:
Override the region and show the full synth output:
Run it from an agent and get a structured result:

​
What Happens

The command runs a gate-before-write ceremony. Nothing reaches disk until every candidate pin passes.
1

Resolve the application

--app must name a detected local application target. Without it, a single detected application is used. Several detected applications produce an error listing them.
2

Authenticate and resolve credentials

The command requires an authenticated session. --target resolves credentials exactly as fjall deploy --target does. --region overrides the region.
3

Synthesise with existing pins

The application is synthesised with any pins already in fjall-config.json applied, mirroring how a deploy threads capacity identity into the assembly.
4

Compute the plan against live templates

The synthesised assembly is diffed against the live CloudFormation templates. A synthesised stack with no live counterpart is recorded and skipped rather than failing the run.
5

Gate the candidate pins

Candidate pins are injected as CDK context, never written to disk first. The application is re-synthesised and the identity-surface gate runs over every pinned slot, both new candidates and pre-existing pins.
6

Write, all or nothing

Pins are written to fjall-config.json under capacityIdentity[appName][targetName][slot] only when every candidate passes. One failing slot means no pins are written at all.
Commit the resulting fjall-config.json change. Pins travel with the project, and deleting one renames every stateful resource in its slot.

​
Dry runs

There is no dry-run flag. The gate-before-write ceremony gives you the equivalent safety: a run that refuses any candidate writes nothing, reports the failing slot and its gate failures, and exits with code 1.

​
Nothing to pin

Three outcomes report no work rather than an error:

​
Exit codes

​
Agent mode

With --agent, the command emits a structured result instead of the human report. The result name is one of: The payload carries app, accountId, region, targetName, clean, duration, plus outcomes and verified arrays when the report has them. Dependency-gate warnings arrive as structured warning events rather than stderr diagnostics.

​
Options

All options belong to the identity subcommand. The fjall migrate group itself accepts only --non-interactive and -v, --verbose. Empty values are rejected at the boundary. --app "" and --target "" fail validation rather than falling back to auto-detection.

​
Next Steps

fjall deploy

Deploy the application once its pins are committed.

Destructive Changes

The rename and consent ceremony that pins protect against.

fjall drift

Detect and repair resources changed outside CloudFormation.

fjall validate

Check infrastructure.ts before the next deploy.