> ## Documentation Index > Fetch the complete documentation index at: https://docs.fjall.io/llms.txt > Use this file to discover all available pages before exploring further. # fjall apps > List, describe, create and detect Fjall applications from one command, with four subcommands, two aliases and a bare-invocation default. **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`](/cli/accounts) | | `fjall account` | **Account-tier** operations: `fjall account deploy`, `fjall account destroy` | [Deploy an account](/deployment/deploy-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 ```bash theme={null} 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 ` | `describe` | | `fjall apps show ` | `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: ```bash theme={null} $ fjall apps banana Error: Unknown subcommand 'banana' Available subcommands: list, describe, create, detect ``` ## apps list ```bash theme={null} 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: ```text theme={null} ✓ 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 ```bash theme={null} fjall apps describe api # or fjall apps show api ``` Prints the name, health and ID, then every scalar field on the application record: ```text theme={null} 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: ```text theme={null} Error: Application name is required Usage: fjall apps describe ``` 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 ```bash theme={null} 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`](/cli/create). 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](#create-options) below. ```bash theme={null} # 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 ```bash theme={null} 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: ```bash theme={null} fjall apps detect ~/code/storefront ``` One row per workspace, each carrying a framework, a suggested name, a port and a pattern recommendation. Pass the recommended **pattern** to `--pattern`. Framework names and pattern names are different vocabularies, and a framework name passed to `--pattern` is refused. ```bash theme={null} 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. ```bash theme={null} fjall deploy storefront-web ``` See [`fjall deploy`](/cli/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 ```text theme={null} 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 ```bash theme={null} fjall apps detect ~/code/storefront --output json ``` One line of JSON on stdout: ```json theme={null} { "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/` 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 ` | `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 ` | Output budget: `minimal`, `compact`, or a token count | | `--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`](/cli/create) registers, so the two commands stay in lockstep. | Option | Description | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-n, --name ` | **Required.** Application name: lowercase letters, numbers and hyphens | | `-t, --type ` | Application tier: `tinkerer`, `lightweight`, `standard`, `resilient`, `enterprise`, `custom` | | `--pattern ` | Application pattern: `payload` or `staticsite` | | `--tier ` | Infrastructure tier for pattern apps: `lightweight`, `standard`, `resilient`, `custom` | | `--pattern-tier ` | Alias for `--tier` | | `--pattern-domain ` | Pattern domain | | `--source ` | Static-site source directory. The build runs here and assets upload from here | | `--build-command ` | Static-site build command, such as `"npm run build"` | | `--output-dir ` | Static-site build output directory, relative to `--source` | | `--routing ` | Static-site routing: `multipage` (`/about` serves `/about.html`), `directory` (`/about/index.html`), `spa` (fall back to `/index.html`) | | `--forms-to ` | Static-site contact-form recipient. Requires `--pattern-domain`, the verified SES sender identity | | `--cors-origin ` | Static-site forms CORS allow-origin. Defaults to the site domain | | `--database` | Include a database | | `--dockerfile [path]` | Path to a Dockerfile | | `--container-port ` | Container port | | `--services ` | Services as a JSON array | | `--owner ` | Application owner | | `--network ` | Network preset: `none`, `tinkerer`, `lightweight`, `standard`, `resilient`, `enterprise` | | `--snapshot-identifier ` | RDS snapshot identifier to restore the database from | | `--snapshot-username ` | Master username for the restored snapshot | | `--template ` | Application template | | `--git` | Initialise a git repository | | `--github` | Create a GitHub repository | | `--github-org ` | GitHub organisation for the repository | | `--repo-visibility ` | Repository visibility: `private` or `public` | | `--into ` | Scaffold into an existing repo at this path instead of `./fjall/`. Must already exist | | `--container ` | 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 ` | Override the active target for this command and persist it to `.fjall/local.json` | | `--file-override ` | 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](/cli/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 The guided application wizard, and the same flag block as `apps create`. List the resources declared inside one application's infrastructure.ts. List provider accounts. The plural sibling that is not this command. Ship an application to AWS once it is created.