Fjall Docs — deploy AWS infrastructure into your own account

Dispatcher command. fjall apps reads its subcommand from the first positional argument. Run it bare and it lists applications.

Overview

fjall apps is the application-level view of your organisation. It carries five subcommands:

Subcommand	Does
`fjall apps list`	Lists every application in your organisation with its health
`fjall apps describe`	Prints what Fjall holds on record for one application
`fjall apps create`	Scaffolds a new application from flags
`fjall apps detect`	Reads a repository and reports what Fjall can build from it
`fjall apps deregister`	Removes an application’s registration, freeing a slot against your plan limit

The accepted surface is exactly those five names plus two aliases. Anything else exits with Unknown subcommand and prints the five canonical names back to you.

Plural and singular are different commands

Three adjacent spellings exist. None of them is a typo of another.

Command	What it does	Reference
`fjall apps`	Manages applications: list, describe, create, detect, deregister	This page
`fjall accounts`	Lists provider accounts, an alias for the non-structural targets	`fjall accounts`
`fjall account`	Account-tier operations: `fjall account deploy`, `fjall account destroy`	Deploy an account

fjall account never lists anything, and fjall accounts never deploys anything. Each command’s own description names the other, because the adjacency is deliberate rather than accidental.

Prerequisites

Subcommand	Needs a Fjall login	Needs an AWS connection
`list`	Yes	For health only. Without it every row reads `unknown`
`describe`	Yes	For health only
`create`	Yes, unless `--offline`	No. Scaffolding writes files and registers the application
`detect`	No. Detection runs before the authentication gate	No. It reads local files
`deregister`	Yes, as an organisation owner or admin on a user credential	No. It deletes the Fjall record and touches no AWS resource

Usage

fjall apps [subcommand] [arg]

The second positional is the subcommand’s argument: an application name for describe and deregister, a path for detect. list and create take no positional.

Subcommands

Spelling	Runs
`fjall apps`	`list` (the bare-invocation default)
`fjall apps list`	`list`
`fjall apps ls`	`list` (alias)
`fjall apps describe <app>`	`describe`
`fjall apps show <app>`	`describe` (alias)
`fjall apps create`	`create`
`fjall apps detect [path]`	`detect`
`fjall apps deregister <app>`	`deregister`

ls and show are accepted but not advertised, so the unknown-subcommand error lists only the five canonical names:

$ fjall apps banana
Error: Unknown subcommand 'banana'
Available subcommands: list, describe, create, detect, deregister

apps list

fjall apps list
# or, identically
fjall apps

Fetches every application in your organisation, then probes each one’s health in parallel. Health comes from two sources: an in-flight deployment record wins outright, and otherwise the state of the application’s network CloudFormation stack decides.

Health	Icon	Meaning
`healthy`	`✓`	The stack is in a deployed state
`unhealthy`	`✗`	The stack exists but is in some other state
`deploying`	`↻`	A deployment is in flight, or the stack is `IN_PROGRESS`
`not-deployed`	`−`	No stack exists yet
`unknown`	`−`	The probe failed on credentials, throttling or network

Output:

  ✓ api          healthy
  ✓ web          healthy
  − dashboard    not-deployed

  3 applications (2 healthy, 1 not deployed)

unknown is not folded into not deployed. One is a definite state, the other is an unreadable one. A summary line reading 1 unknown means the health probe could not answer, not that the application is missing.

At a terminal, fjall apps list renders in the interactive UI, prints the same rows and exits. It presents no menu and selects nothing. Pass --non-interactive for plain output.

apps describe

fjall apps describe api
# or
fjall apps show api

Prints the name, health and ID, then every scalar field on the application record:

  Name:   api
  Health: ✓ healthy
  ID:     app_01hz8k3m2p4q
  createdAt: 2026-01-14T09:22:11.004Z
  organisationId: org_01hy4c8n1x

Nested objects are skipped, so the output stays one field per line. Omit the name and the command refuses before doing any work:

Error: Application name is required
Usage: fjall apps describe <app>

An application that genuinely does not exist reports Application "api" not found. A credential or network failure reports its own message instead, so a blip is never presented as a missing application.

apps create

fjall apps create --name api --type standard

Scaffolds an application from flags and registers it with Fjall. --name is required: without it the command fails with Application creation requires a name.

fjall apps create never opens the interactive wizard, even at a terminal. The guided six-tier flow lives on fjall create app. The two commands share the same flag block, so anything you can pass to one you can pass to the other.

Its full option set is in Create options below.

# Preview without writing anything
fjall apps create --name api --type standard --dry-run

# Payload CMS pattern, lightweight tier, scaffolded into an existing repo
fjall apps create \
  --name storefront-web \
  --pattern payload \
  --tier lightweight \
  --database \
  --dockerfile apps/web/Dockerfile \
  --container-port 3000 \
  --into ~/code/storefront

apps detect

fjall apps detect [path]

Reads a repository and reports what Fjall can build from it. With no path it scans the current directory. A relative path resolves against the current directory, and a path that is not an existing directory is refused. Detection is the first step of the application-creation recipe, and it is mandatory for an existing repository. The values it reports are the values apps create asks for, so running it first removes the guesswork:

Detect

fjall apps detect ~/code/storefront

One row per workspace, each carrying a framework, a suggested name, a port and a pattern recommendation.

Read the recommendation, not the framework

Pass the recommended pattern to --pattern. Framework names and pattern names are different vocabularies, and a framework name passed to --pattern is refused.

Create

fjall apps create --name storefront-web --pattern payload --tier lightweight --into ~/code/storefront

Seed the flags from the detected row: suggestedAppName for --name, and the create block’s source, buildCommand and outputDir for a static site.

Deploy

fjall deploy storefront-web

See fjall deploy.

What detection reads

A workspace is classified from its package.json dependencies. A monorepo is expanded through its workspace globs, so every workspace gets its own row.

Framework signal	Detected as	Pattern verdict
`next` and `payload`	`nextjs+payload`	Recommended: `payload`
`payload`	`payload`	Recommended: `payload`
`astro`	`astro`	Recommended: `staticsite`
`next`	`nextjs`	Blocked. No CDK construct, so the pattern is refused
`@remix-run/node`	`remix`	Unsupported. Fjall has no request-time server pattern
`express`	`express`	Unsupported. Same reason
No recognised signal	`unknown`	Unsupported. For a pre-built static site, pass `--pattern staticsite` with `--source`, `--build-command` and `--output-dir`

Monorepo tools recognised: npm-workspaces, pnpm, lerna, turbo, nx. A workspace with no framework and no Dockerfile is classified library, and Fjall will not scaffold infrastructure around it.

Human output

Fjall framework detection — /Users/you/code/storefront
Repo type: monorepo (npm-workspaces)
Root package: storefront

Detected 1 app(s):

  apps/web
    framework: nextjs+payload
    package:   @storefront/web
    dockerfile: apps/web/Dockerfile
    port:      3000
    suggested name:        storefront-web
    suggested config path: fjall/storefront-web

Only the facts go to stdout: the Repo type: and Root package: lines, then for each detected application a blank line, its path, and its framework, package, dockerfile, port, suggested name and suggested config path lines. Everything else goes to stderr. That covers the Fjall framework detection header, the Detected N app(s): line, the No scaffoldable apps detected sentence and every warning, so a piped stdout carries only the detection facts. An empty result is reported honestly. When the scan hit warnings, detection says the scan was degraded and that paths it could not read were never scanned, rather than asserting the repository holds nothing.

JSON output

fjall apps detect ~/code/storefront --output json

One line of JSON on stdout:

{
  "ok": true,
  "data": {
    "isMonorepo": true,
    "monorepoTool": "npm-workspaces",
    "rootPackageName": "storefront",
    "apps": [
      {
        "relativePath": "apps/web",
        "framework": "nextjs+payload",
        "packageName": "@storefront/web",
        "hasDockerfile": true,
        "docker": { "path": "apps/web/Dockerfile" },
        "inferredPort": 3000,
        "suggestedAppName": "storefront-web",
        "suggestedConfigPath": "fjall/storefront-web",
        "role": "application",
        "recommendation": {
          "kind": "recommended",
          "pattern": "payload",
          "rationale": "Payload v3 ships as a Next.js plugin, so a repository carrying both dependencies is a Payload application and deploys as one."
        },
        "create": {
          "pattern": "payload",
          "source": "../..",
          "buildCommand": "npm run build",
          "outputDir": null,
          "routing": null
        }
      }
    ],
    "warnings": []
  }
}

A failure writes {"ok": false, "error": { … }} and exits 1. In human mode the same failure prints Detection failed: … to stderr.

create.outputDir is a framework convention, not a verified path. Build the site and confirm the directory exists before you deploy, or the deploy succeeds and serves an empty bucket.

create.source is relative to the application’s fjall/<name> config directory, not the repository root. The leading ../.. is part of the value. Pass it to --source verbatim.

apps deregister

fjall apps deregister property --confirm property

Removes an application’s registration from Fjall, and nothing else. This is the only verb that frees a slot against your plan’s application limit.

De-registration is irreversible: nothing restores the record, and afterwards the CLI can no longer address the application by name — fjall destroy included. If you want the AWS infrastructure gone, destroy first, de-register second.

Destroying does not free the slot

fjall destroy tears the CloudFormation stacks down and deliberately leaves the record behind, so the application can be redeployed later and its history survives. That record is what the plan counts, so a destroy alone never gets an organisation under its limit:

$ fjall destroy property          # stacks gone, record kept
$ fjall apps list
  − property      not-deployed
  ✓ electrical    healthy

  2 applications (1 healthy, 1 not deployed)
$ fjall deploy electrical --plan
Error: Application limit reached (2/1 on Free plan). Upgrade your plan to deploy more
applications, or free a slot with `fjall apps deregister <app> --confirm <app>`.
Destroying an application does not free its slot, because the registration is what
the limit counts.

The refusal arrives as one line. A link to the Change plan page is appended to it when the server can build one. The sequence that clears both:

Destroy the infrastructure

fjall destroy property

Optional, and it has to come first. Skip it only if you want the AWS resources to keep running, because de-registering leaves them in place with nothing in the CLI able to name them.

De-register the record

fjall apps deregister property --confirm property

The slot is free the moment this returns.

`--confirm` retypes the name

--confirm must match the application name exactly. It is checked before the authentication gate, so a missing or mismatched value costs no round trip and tells you the real mistake:

Error: De-registering requires --confirm <app> matching the application name, e.g. `fjall apps deregister <app> --confirm <app>`.
Usage: fjall apps deregister <app> --confirm <app>

A value that does not match is refused, and the refusal names the application it expected:

Error: --confirm must match the application name exactly (expected `property`). De-registration removes the application from Fjall and cannot be undone.
Usage: fjall apps deregister <app> --confirm <app>

Leaving the application name off is refused on the same side of the gate:

Error: Application name is required
Usage: fjall apps deregister <app> --confirm <app>

There is no --yes. A retype names its subject, so consent given for one application cannot be replayed against another. On success:

==> [1/1] De-registering property
  ✓ property de-registered — the application slot is free.
  − This removed the registration only — any AWS infrastructure the application still has is untouched, and the CLI can no longer address it by name. Run `fjall destroy <app>` BEFORE de-registering if you want the infrastructure gone.
<== [1/1] De-registering property (0.4s)

Who can run it

An organisation owner or admin, signed in on a user credential — the fj_ key fjall login writes. A scoped machine token (fjall_ak_, fjall_dk_) is refused, because de-registration is a membership-role decision rather than a token-scope one.

Refusals

Every refusal below leaves the record exactly where it was.

Condition	What happens
A deployment is in flight	Refused, naming the deployment and its status. Wait for it to finish or cancel it, then try again
Live dev-environment resources still exist	Refused, naming the slots and substrates. Tear them down with `fjall dev substrate down <app>`, then try again
No application of that name	Refused as not found
More than five de-registrations in a minute	Rate-limited per organisation. Retry after a minute

Options

Command options

Option	Applies to	Description
`--output <format>`	`detect` only	`human` or `json`. Defaults to `human`
`--mcp-protocol`	`create` only	Emit structured JSONL frames on stdout for MCP server consumption
`--confirm <app>`	`deregister` only	Retype the application name to confirm. Checked before the authentication gate

--mcp-protocol on any other subcommand emits an INVALID_SUBCOMMAND frame and exits 2. It never falls through to a human render, because a failure path that wrote to stdout would corrupt the frame stream.

Shared flags

Option	Description
`--non-interactive`	Force plain CLI output with no interactive UI
`-v, --verbose`	Enable verbose output
`--agent`	Enable agent output mode
`--budget <level>`	Output budget: `minimal`, `compact`, or a token count
`--fields <fields>`	Select exactly these output fields
`--full`	Disable content truncation

Create options

Every flag below is registered on fjall apps but read only by apps create. This is the same block fjall create app registers, so the two commands stay in lockstep.

Option	Description
`-n, --name <name>`	Required. Application name: lowercase letters, numbers and hyphens
`-t, --type <type>`	Application tier: `tinkerer`, `lightweight`, `standard`, `resilient`, `enterprise`, `custom`
`--pattern <pattern>`	Application pattern: `payload` or `staticsite`
`--tier <tier>`	Infrastructure tier for pattern applications: `lightweight`, `standard`, `resilient`, `custom`
`--pattern-tier <tier>`	Alias for `--tier`
`--pattern-domain <domain>`	Pattern domain
`--source <dir>`	Static-site source directory. The build runs here and assets upload from here
`--build-command <cmd>`	Static-site build command, such as `"npm run build"`
`--output-dir <dir>`	Static-site build output directory, relative to `--source`
`--routing <mode>`	Static-site routing: `multipage` (`/about` serves `/about.html`), `directory` (`/about/index.html`), `spa` (fall back to `/index.html`)
`--forms-to <email>`	Static-site contact-form recipient. Requires `--pattern-domain`, the verified SES sender identity
`--cors-origin <origin>`	Static-site forms CORS allow-origin. Defaults to the site domain
`--database`	Include a database
`--dockerfile [path]`	Path to a Dockerfile
`--container-port <port>`	Container port
`--services <json>`	Services as a JSON array
`--owner <owner>`	Application owner
`--network <preset>`	Network preset: `none`, `tinkerer`, `lightweight`, `standard`, `resilient`, `enterprise`
`--snapshot-identifier <id>`	RDS snapshot identifier to restore the database from
`--snapshot-username <name>`	Master username for the restored snapshot
`--template <name>`	Application template
`--git`	Initialise a git repository
`--github`	Create a GitHub repository
`--github-org <org>`	GitHub organisation for the repository
`--repo-visibility <visibility>`	Repository visibility: `private` or `public`
`--into <path>`	Scaffold into an existing repo at this path instead of `./fjall/<name>`. Must already exist
`--container <dir>`	Monorepo container directory between the repo root and the application’s `fjall/` marker, such as `apps` or `services`. Blank or whitespace-only values are rejected
`--dry-run`	Preview the scaffold without writing files, calling the API, or installing dependencies
`--offline`	Scaffold with no network at all: no authentication, no Fjall API call, no npm install. Files are written but the application is not registered, and only free tiers work
`--register-only`	Register an existing application tree without scaffolding: no files written, no npm install, no git. Run from the application’s package root
`--target <name>`	Override the active target for this command and persist it to `.fjall/local.json`
`--file-override <relpath=base64>`	Override a planned scaffold file with base64-encoded content. Repeatable, and the path must match a file the generator was about to write

--pattern nextjs parses but is refused at creation: the Next.js pattern has no CDK construct yet, so nothing is scaffolded and nothing is written. Use --pattern payload for a Next.js-based application, or supply a static export with --pattern staticsite.

--tier and --type belong to different application modes and are mutually exclusive. --tier carries the pattern tier for --pattern applications, --type carries the tier for Dockerfile applications. Crossing them is refused with an error naming the correct flag.

Agent mode

All five subcommands have an agent surface. --agent renders TOON instead of tables, and --fields is validated against that subcommand’s schema before the authentication gate, so a typo fails fast rather than after a round trip.

Surface	Default fields
`apps list`	`name`, `health`
`apps describe`	`name`, `health`, `id`
`apps create`	`name`
`apps detect`	`path`, `framework`, `role`, `pattern`, `name`, `source`, `buildCommand`, `outputDir`
`apps deregister`	`name`, `deregistered`

On apps deregister the receipt carries deregistered: true beside name. It is a field rather than an implied truth of the success block, because it says the Fjall record is gone and says nothing about the AWS stack. Select id alongside them:

fjall apps deregister property --confirm property --agent --fields name,deregistered,id

The success help block carries two suggestions, both pointing at what is still standing:

help[2]:
  - "Check the AWS console for any stack the application still has — de-registering removed the Fjall record only, and the CLI can no longer address it by name"
  - "Run `fjall apps list --agent` to confirm the application count against your plan limit"

On apps detect, agent mode is checked before --output. Passing --agent --output json renders TOON, not JSON. Omit --agent when a subprocess needs the JSON contract — nothing else turns agent mode on.

Full reference: Agent mode.

Exit codes

Code	Meaning
`0`	The subcommand succeeded
`1`	The subcommand failed, including a detection failure and an unknown subcommand
`2`	`--mcp-protocol` validation error, such as using it on a subcommand other than `create`

Next Steps

fjall create

The guided application wizard, and the same flag block as apps create.

fjall list

List the resources declared inside one application’s infrastructure.ts.

fjall accounts

List provider accounts. The plural sibling that is not this command.

fjall deploy

Ship an application to AWS once it is created.

Core Commands

Infrastructure Codemods

Insights

Management Commands

Build & CI

Environments & Data

Diagnostics & Recovery

Authentication

Agent Mode

fjall apps

Overview

Plural and singular are different commands

Prerequisites

Usage

Subcommands

apps list

apps describe

apps create

apps detect

What detection reads

Human output

JSON output

apps deregister

Destroying does not free the slot

`--confirm` retypes the name

Who can run it

Refusals

Options

Command options

Shared flags

Create options

Agent mode

Exit codes

Next Steps

fjall create

fjall list

fjall accounts

fjall deploy

​Overview

​Plural and singular are different commands

​Prerequisites

​Usage

​Subcommands

​apps list

​apps describe

​apps create

​apps detect

​What detection reads

​Human output

​JSON output

​apps deregister

​Destroying does not free the slot

​--confirm retypes the name

​Who can run it

​Refusals

​Options

​Command options

​Shared flags

​Create options

​Agent mode

​Exit codes

​Next Steps

fjall create

fjall list

fjall accounts

fjall deploy

Overview

Plural and singular are different commands

Prerequisites

Usage

Subcommands

apps list

apps describe

apps create

apps detect

What detection reads

Human output

JSON output

apps deregister

Destroying does not free the slot

`--confirm` retypes the name

Who can run it

Refusals

Options

Command options

Shared flags

Create options

Agent mode

Exit codes

Next Steps