Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

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 four 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

The accepted surface is exactly those four names plus two aliases. Anything else exits with Unknown subcommand and prints the four 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	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

Usage

fjall apps [subcommand] [arg]

The second positional is the subcommand’s argument: an application name for describe, 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`

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

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

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 app-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

Warnings go to stderr, so a piped stdout stays clean. 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 app’s fjall/<name> config directory, not the repository root. The leading ../.. is part of the value. Pass it to --source verbatim.

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

--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 apps: `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 app’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 app tree without scaffolding: no files written, no npm install, no git. Run from the app’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 apps, --type carries the tier for Dockerfile apps. Crossing them is refused with an error naming the correct flag.

Agent mode

All four 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`

On apps detect, agent mode is checked before --output. Passing --agent --output json renders TOON, not JSON. Pass --no-agent when a subprocess needs the JSON contract and its environment would otherwise auto-engage agent mode.

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

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

​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

Options

Command options

Shared flags

Create options

Agent mode

Exit codes

Next Steps