Fjall Docs — deploy AWS infrastructure into your own account

fjall add edits an application’s infrastructure.ts through the codemod engine. It does not touch AWS. Run fjall deploy <app> afterwards to apply the change.

Overview

fjall add appends a resource to an existing application’s infrastructure.ts. It writes valid CDK code, wires connections to sibling resources, typechecks the edited file, and reports the lines changed. The command runs the codemod engine directly in both human and agent modes. There is no interactive resource picker on this path. <type>, --app and --name are all required, and a missing one exits with a validation error rather than opening a prompt.

The Ink resource wizard still exists, but the only route into it is the “add your first resource” hand-off shown after fjall create app for a custom-tier application. Typing fjall add never opens it.

Usage

fjall add <type> --app <app> --name <Name> [--<property> <value> ...]

Token	Meaning
`<type>`	Required. The resource category (see Resource types).
`--app <app>`	Required. The application to edit.
`--name <Name>`	Required. Resource name, PascalCase by convention.
`[--<property> <value> ...]`	Resource-specific configuration as repeated `--<name> <value>` pairs.

Resource types

<type> is one of these twelve exact values:

Type	Adds
`database`	A managed database (Aurora, RDS instance, GlobalAurora, ClickHouse).
`compute`	A compute service (`ecs`, `lambda`, or `ec2`).
`storage`	An S3 bucket.
`cdn`	A CloudFront distribution.
`messaging`	An SQS queue (standard or FIFO).
`network`	An additional VPC.
`pattern`	A higher-level pattern composition (Payload CMS or static site).
`vpc-peer`	A VPC peering requester.
`vpc-peer-accepter`	A VPC peering accepter.
`cross-plan-connection`	A connection to a resource in another application.
`organisation`	Organisation-tier configuration inside an organisation scaffold.
`buildkite`	A Buildkite agent fleet.

There is no proxy or service type, and there is no colon syntax. A database variant, RDS proxy, or additional ECS service is configured with property flags, not a separate type. fjall add database:Aurora is invalid.

Required properties

The add contract keeps every non-optional schema key required, so a missing one is refused before the file is touched and the error names the key.

Type	Properties required on add
`database`	`--type`, `--databaseName`
`compute`	`--type`, `--needsConnection`
`cdn`	`--defaultOriginRef`
`pattern`	`--type` (`payload` or `staticsite`)
`buildkite`	`--buildkiteQueue`, `--buildkiteOrgSlug`
`vpc-peer`	`--peerAppName`, `--peerAccountId`
`vpc-peer-accepter`	`--requesterAccountIds`
`cross-plan-connection`	`--localResource`, `--remoteApp`, `--remoteResource`, `--permission`
`storage`	None
`messaging`	None
`network`	None
`organisation`	None

Property flags

Any flag the add command does not register (see Options) is treated as a resource property. Flag names are the camelCase keys of the resource schema, so --snapshotIdentifier and --databaseName are correct and --snapshot-identifier is not. Four parsing rules apply:

Each flag consumes the next token as its value. A trailing flag with no value is rejected.
A flag immediately followed by another --flag is rejected. There are no value-less booleans, so pass an explicit value such as --deletionProtection true.
Duplicate flags are rejected so typos surface instead of being silently overwritten.
A value starting with { or [ must parse as JSON. A malformed payload is an error, never a string literal.

Unknown property names are refused with the nearest match suggested, so a mistyped --maxazs is reported against maxAzs rather than written into the construct.

Presets and tiers

--preset and --tier are selectors. They expand into the same explicit properties you could have typed by hand, and nothing named preset or tier ever reaches the emitted statement.

Selector	Applies to	Values
`--preset <name>`	`storage`	`standard`, `assets`, `upload`, `website`
`--tier <tier>`	`database`, `network`	`tinkerer`, `lightweight`, `standard`, `resilient`, `enterprise`

Three rules govern them:

The two cannot be combined. Use --preset for storage and --tier for database and network.
--tier on a database also needs --type, because a tier describes each database type differently.
Explicit property flags win over the preset, so a preset stays a starting point rather than something to avoid when you want to override one key.

--tier is refused on fjall add compute. A compute tier preset is keyed by compute type and carries scaffold placeholders only fjall apps create --tier fills in.

# Expand the upload preset (CORS rules) into an S3 bucket
fjall add storage --app api --name Uploads --preset upload

# Expand the resilient tier's Aurora preset, then override one key
fjall add database --app api --name Analytics --type Aurora \
  --databaseName analytics --tier resilient --backupRetention 30

Examples

Add a database

database is always the type. Choose the variant with --type (Aurora, Instance, GlobalAurora, or ClickHouse) and name the logical database with --databaseName:

fjall add database --app api --name Analytics --type Aurora --databaseName analytics
fjall add database --app api --name Sessions --type Instance --databaseName sessions

The codemod emits DatabaseFactory.build("Analytics", { type: "Aurora", databaseName: "analytics" }).

Add a compute service

--needsConnection says whether the service reaches a sibling resource. Pass false for a standalone service:

# Standalone Lambda function
fjall add compute --app api --name OrderProcessor --type lambda --needsConnection false

# ECS service on Fargate Spot for cost savings (capacityProvider is per-service)
fjall add compute --app api --name Worker --type ecs --needsConnection false \
  --services '[{"name": "worker", "capacityProvider": "FARGATE_SPOT"}]'

An EC2 group takes --sshAccess as a JSON object. allowedIpCidrs is required; omit keyName to have a key pair created, and public to keep the instances private. Leave the flag out for Session Manager-only access:

fjall add compute --app api --name Bastion --type ec2 --needsConnection false \
  --instanceType t4g.nano --sshAccess '{"allowedIpCidrs": ["203.0.113.4/32"], "public": true}'

To wire the service to an existing database, name it and set --needsConnection true:

fjall add compute --app api --name Api --type lambda \
  --needsConnection true --connectedDatabase '["Analytics"]'

Add a storage bucket

fjall add storage --app api --name Uploads

Add a CDN distribution

--defaultOriginRef names a storage or compute resource already declared in the same infrastructure.ts:

fjall add cdn --app web --name Assets --defaultOriginRef Uploads

Restore a database from a snapshot

Pass the snapshot details as property flags. The master username is baked into the snapshot:

fjall add database --app api --name Restored --type Instance --databaseName restored \
  --snapshotIdentifier rds:my-production-snapshot \
  --snapshotUsername postgres

The master username is immutable and baked into the snapshot. It must match the original database’s username exactly.

Add an RDS proxy

A proxy is a property of a database resource. It takes a JSON object or the literal false, never true. Pass --proxy '{}' for the defaults:

fjall add database --app api --name Sessions --type Instance --databaseName sessions \
  --proxy '{"maxConnections": 50, "requireTLS": true}'

Options

These are the flags add registers. Everything else is a property flag.

Option	Description
`-a, --app <name>`	Application to add the resource to (required).
`-n, --name <name>`	Resource name (required).
`--preset <name>`	Storage only. Expand a storage preset into properties.
`--tier <tier>`	Database and network only. Expand that tier’s preset into properties.
`--no-verify`	Skip the post-write typecheck of the edited `infrastructure.ts`.
`-v, --verbose`	Enable verbose logging.
`--non-interactive`	Force plain CLI output (no UI).

Agent options

For AI-agent and scripted use, add also accepts the standard agent flags:

Option	Description
`--agent`	Enable agent output mode.
`--budget <level>`	Output budget: `minimal`, `compact`, or token count.
`--fields <fields>`	Select exactly these output fields.
`--full`	Disable content truncation.

CI and scripted use

add never prompts, so it is already safe in a pipeline. Pass --non-interactive to force plain output:

# Aurora database
fjall add database --app api --name Analytics --type Aurora \
  --databaseName analytics --non-interactive

# Lambda function
fjall add compute --app api --name Worker --type lambda \
  --needsConnection false --non-interactive

# ECS service on Fargate Spot
fjall add compute --app api --name Api --type ecs --needsConnection false \
  --services '[{"name": "api", "capacityProvider": "FARGATE_SPOT"}]' --non-interactive

Connection wiring

Adding a resource with --needsConnection true plus a --connectedDatabase, --connectedStorage, or --connectedMessaging name resolves that name to the sibling’s binding and writes the wiring the construct reads. Neither needsConnection nor the connected name survives into the emitted config. A compute connected to a database called Primary emits:

app.addCompute(
  ComputeFactory.build("Api", {
    type: "lambda",
    deployment: "container",

    environment: {
      DATABASE_HOST: primary.getHostEndpoint(),
      DATABASE_PORT: primary.getHostPort(),
      DATABASE_NAME: primary.getDatabaseName(),
      DATABASE_SSL: "true",
    },

    secretsImport: {
      DATABASE_USERNAME: primary.getCredentials().getImport("username"),
      DATABASE_PASSWORD: primary.getCredentials().getImport("password"),
    },

    connections: [primary],
  }),
);

Env-var names by resource type:

Connected resource	Env vars
Database	`DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_SSL`, plus credentials from Secrets Manager
Storage	`BUCKET_NAME`
Messaging	`QUEUE_URL`, `QUEUE_ARN`

The first connection of a kind carries no suffix. A second gets _2, a third _3, so two databases on one service produce DATABASE_HOST and DATABASE_HOST_2.

Resource naming

Resource names must start with a letter and contain letters and digits only. PascalCase is the convention rather than a rule, so Analytics and analytics both validate. Names must be unique within the application. Pick descriptive ones such as Analytics, Sessions, or Uploads so resources stay easy to identify later. If a name conflicts with an existing resource, the codemod reports the conflict instead of overwriting.

After adding a resource

Review the modified infrastructure.ts. add typechecks it for you unless you passed --no-verify.
List the application’s resources to confirm the change: fjall list --app api.
Deploy to apply the change to AWS: fjall deploy api.

Next Steps

fjall deploy

Apply the new resource to AWS.

fjall list

List the resources in an application’s infrastructure.ts.

fjall modify

Change the properties of a resource you already added.

fjall remove

Remove a resource from an application’s infrastructure.ts.

fjall validate

Check the edited infrastructure.ts before deploying.

Add resources guide

Walk through adding resources to an application end to end.

Core Commands

Infrastructure Codemods

Insights

Management Commands

Build & CI

Environments & Data

Diagnostics & Recovery

Authentication

Agent Mode

fjall add

Overview

Usage

Resource types

Required properties

Property flags

Presets and tiers

Examples

Add a database

Add a compute service

Add a storage bucket

Add a CDN distribution

Restore a database from a snapshot

Add an RDS proxy

Options

Agent options

CI and scripted use

Connection wiring

Resource naming

After adding a resource

Next Steps

fjall deploy

fjall list

fjall modify

fjall remove

fjall validate

Add resources guide

​Overview

​Usage

​Resource types

​Required properties

​Property flags

​Presets and tiers

​Examples

​Add a database

​Add a compute service

​Add a storage bucket

​Add a CDN distribution

​Restore a database from a snapshot

​Add an RDS proxy

​Options

​Agent options

​CI and scripted use

​Connection wiring

​Resource naming

​After adding a resource

​Next Steps

fjall deploy

fjall list

fjall modify

fjall remove

fjall validate

Add resources guide

Overview

Usage

Resource types

Required properties

Property flags

Presets and tiers

Examples

Add a database

Add a compute service

Add a storage bucket

Add a CDN distribution

Restore a database from a snapshot

Add an RDS proxy

Options

Agent options

CI and scripted use

Connection wiring

Resource naming

After adding a resource

Next Steps