fjall

The Fjall CLI. It authors a TypeScript declaration of your infrastructure, then deploys it with CloudFormation into your own AWS account — Fjall holds no copy of your resources, and AWS bills you directly for everything it creates.

npm install -g fjall

Node 22.3 or newer. Also available through Homebrew:

brew install fjall-tech/tap/fjall

Try it without an account

--offline scaffolds a real project with no authentication and no Fjall API call, so you can read the code Fjall would deploy before deciding anything:

npx fjall create app --offline --name my-api

It writes fjall/my-api/infrastructure.ts and stops there — the app is not registered, and dependencies are not installed. Run npm install in the generated directory before synthesising. Only the free tiers (tinkerer, lightweight, standard, custom) are available offline.

The file it writes is ordinary CDK in your repository. You can read it, diff it, and keep it.

Setting up for real

fjall login
fjall create account        # scaffolds fjall/account/infrastructure.ts
fjall connect               # installs Fjall's OIDC trust in your AWS account
fjall account deploy        # deploy roles, logging and guardrails

fjall create organisation / fjall org deploy is the same three steps for an AWS Organizations management account, which additionally creates member accounts.

Exit codes distinguish a refusal from a failure

The CLI's numeric exit space is a stable contract, owned in one file (cli/src/util/exitCodes.ts):

| Code | Meaning | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | | 0 | Success — applied, or nothing to apply | | 1 | Error | | 2 | The deploy stopped without failing — a plan is pending approval, was rejected at the gate, or the run was cancelled remotely | | 4 | The destruction ceremony stopped the deploy. Nothing was applied — a human has to decide | | 10–19 | Codemod band (10 user error, 11 state conflict, 12 I/O error) | | 64 | A prerequisite is missing (Docker buildx) | | 129/130/143 | Signal exits |

2 and 4 are not failures, and scripting them as failures is the most common mistake. fjall aws exec and fjall secrets exec pass the wrapped child's exit code through verbatim, so read the child's contract for those, not this table.

What it does not do

Named here because finding out mid-tutorial is worse:

• fjall import adopts S3 buckets only. Anything else refuses by name and tells you to re-run with --resource-type s3. Discovery is broader than adoption — it will find far more than it can author.
• fjall add messaging authors SQS queues. Topics and event buses exist in the construct library but the generator does not emit them.
• fjall doctor runs one check — stale CDK temp directories. --clean-cdk-tmpdir removes them.
• Patterns that deploy are Payload CMS and a pre-built static site. The static-site pattern refuses creation without --source, --build-command and --output-dir. Next.js scaffolds but does not deploy — no construct exists yet.

Notes

--offline skips authentication, registration and npm install, but the process still performs a once-daily npm version check on start-up. Set CI=1 to suppress it.

Every command writes its result to stdout and its progress, warnings and failure reports to stderr; a command that could not produce its result leaves stdout empty and exits non-zero. Pass --agent for machine output (TOON on stdout) — it is never inferred from the environment, so a script gets the same bytes wherever it runs.

Licence

Proprietary. See the bundled LICENSE: a non-exclusive, non-transferable and revocable licence to install from npm and run Fjall for your own applications. Redistribution, modification and reverse engineering are prohibited. This package is not open source.

Documentation: https://docs.fjall.io