Skip to main content
Local command. Parses an application’s infrastructure.ts with the codemod engine and reports whether it is valid. It deploys nothing and changes nothing in AWS. Without --synth it makes no AWS calls. With --synth, the CDK CLI it runs can call AWS STS to choose the default account of the stacks it synthesises (see The AWS SDK can still read your AWS profiles).
  • An application created with fjall create app, so an infrastructure.ts file exists.
  • Run the command from your project root (where the fjall/ directory lives).
  • Node 22.3 or later.
  • --deep needs the application’s TypeScript toolchain to resolve.
  • --synth additionally needs the application’s dependencies installed, because it runs the real CDK synthesiser.

Validate an application

Parse the infrastructure.ts for a single application:
Add a typecheck:
Add a local CloudFormation synthesis, the strongest pre-deploy gate:
--app is required. The three levels stack. --synth on its own is refused with Invalid invocation: --synth requires --deep.

What Happens

  1. Resolves the infrastructure.ts path for the application you pass to --app, against your current directory.
  2. Parses the file with the codemod engine (an AST parse, no AWS calls) and prints Parse: OK.
  3. With --deep, typechecks the application and prints Typecheck: OK, or Typecheck: FAILED with the type errors.
  4. With --deep --synth, synthesises the CloudFormation template on your machine and prints Synth: OK, or Synth: FAILED with the CDK error. Synth runs only above a green typecheck.
Without --synth, the command reads local files only. It never contacts AWS, writes to infrastructure.ts, or touches the .fjall history directory, so there is nothing to dry-run. --synth writes the synthesised template tree to cdk.out/ beside the application, with the CDK’s context lookups turned off, and deploys nothing. Fjall runs the CDK CLI with no AWS credentials of its own, so the CDK CLI looks for credentials itself. When it finds some, it asks AWS STS (GetCallerIdentity) which account they belong to, unless it has cached that account already, and the account becomes the default account of the synthesised stacks. Where it looks, and how to choose the account it takes, is in The AWS SDK can still read your AWS profiles.

--deep checks the whole application

Every Fjall-scaffolded application ships a tsconfig.json next to infrastructure.ts, so --deep runs tsc --project <app>/tsconfig.json --noEmit. A type error anywhere in that project fails the check, not only errors in infrastructure.ts. Applications with no tsconfig.json fall back to checking infrastructure.ts alone. The typecheck times out after 60 seconds, synth after 5 minutes. A timeout is reported as a failure.

Output

A successful parse prints the absolute resolved path:
A deep synth run appends both later stages:
In a terminal, runs without --synth render a progress screen instead of plain text. --synth always uses the plain-text lane. Pass --non-interactive for plain text everywhere.

Agent mode

Pass --agent to emit structured output for AI agents. The result carries action, target (the application), path, parse, typecheck and synth, plus details when the typecheck failed and synthDetails when synth failed. typecheck and synth each read ok, failed or skipped. synth reads skipped unless you passed --synth and the typecheck came back green. A failed typecheck or synth exits non-zero.

Exit codes

Wire fjall validate into a CI gate ahead of fjall deploy and branch on the exit code.

Options

Next steps

fjall deploy

Deploy a validated application’s infrastructure to AWS.

fjall add

Add a resource to an application’s infrastructure.

fjall list

List the resources declared in an application’s infrastructure.

CI/CD deploys

Gate a pipeline on validation before it deploys.