> ## 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 status

> Check the deployment health of every Fjall application, or one named application, from a single read-only CLI command.

<Info>
  **Read-only command.** `fjall status` queries the Fjall API and
  CloudFormation and prints a health report. It never changes AWS and never
  edits a file.
</Info>

## Overview

`fjall status` answers one question: which of my applications are up?

The application argument is optional, and it decides the scope of the report:

| Invocation         | What it reports                                                 |
| ------------------ | --------------------------------------------------------------- |
| `fjall status`     | Every application registered to your organisation, one row each |
| `fjall status api` | The single application named `api`, in the same table shape     |

Both paths resolve the application from the Fjall API. Neither reads
`fjall-config.json`, so you can run the command from any directory. An
application name that your organisation does not carry is an error, not an
empty table.

## Prerequisites

| Requirement                 | Why                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| A signed-in session         | The application list comes from the Fjall API. Run [`fjall login`](/cli/login) first                                    |
| A connected AWS account     | Health comes from a CloudFormation probe. Run [`fjall connect`](/cli/connect) first                                     |
| An active deployment target | The probe runs in the account and region the active target resolves to. Check it with [`fjall target get`](/cli/target) |

Missing credentials fail before the query with `Authentication required.` plus
the cure for your environment: `fjall login` at a terminal, `FJALL_API_KEY` on a
CI runner. An unreadable AWS connection does not fail the command. The health
probe degrades to `unknown` and the report still prints.

## Usage

```bash theme={null}
fjall status [app]
```

## Arguments

| Argument | Description                      | Required |
| -------- | -------------------------------- | -------- |
| `app`    | Report on this application alone | No       |

## What the output shows

Two columns and a count line.

```bash theme={null}
fjall status
```

```
==> [1/1] Querying application status
    Name        Health
    -----------------------
    api         ✓ healthy
    web         ↻ deploying
    dashboard   − not-deployed

  3 applications (1 healthy, 1 deploying, 1 not deployed)
<== [1/1] Querying application status (2s)

── Summary ───────────────────────────────────────
  Result:   ✓ all applications queried successfully
  Duration: 2s
  Count:    3
──────────────────────────────────────────────────
```

The count line lists only the non-zero buckets, in the order healthy,
unhealthy, deploying, not deployed, unknown.

Naming an application narrows the table to one row and names it in the summary:

```bash theme={null}
fjall status api
```

```
    Name   Health
    ------------------
    api    ✓ healthy

  1 application (1 healthy)
```

An organisation with no applications prints `− No applications found` in place
of the table, and the summary reports `Count:    0`.

### Health values

| Value          | Icon | Meaning                                                                                                    |
| -------------- | ---- | ---------------------------------------------------------------------------------------------------------- |
| `healthy`      | `✓`  | The network stack is `CREATE_COMPLETE`, `UPDATE_COMPLETE`, `UPDATE_ROLLBACK_COMPLETE` or `IMPORT_COMPLETE` |
| `unhealthy`    | `✗`  | The stack exists in some other settled state, such as `CREATE_FAILED` or `ROLLBACK_COMPLETE`               |
| `deploying`    | `↻`  | A deployment record is in flight, or the stack is `*_IN_PROGRESS`                                          |
| `not-deployed` | `−`  | No stack exists for the application yet                                                                    |
| `unknown`      | `−`  | The probe could not read the state (expired credentials, throttling, network)                              |

<Warning>
  `unknown` is not `not-deployed`. One says the state could not be read, the
  other says the state was read and there is nothing there. The count line and
  the machine-readable aggregates keep them apart, so never fold them together
  in a script.
</Warning>

### How health is derived

Two signals, in order:

<Steps>
  <Step title="In-flight deployment records">
    Fjall reads your organisation's recent deployment records. An application
    with a record in `queued`, `pending`, `running` or `cancelling` reports
    `deploying`, whatever CloudFormation says. A compute-only rollout never
    moves the network stack, so this signal is what makes those deploys
    visible.
  </Step>

  <Step title="The network CloudFormation stack">
    Otherwise Fjall reads the status of the application's network stack
    (`api` becomes `ApiNetwork`) and maps it to one of the five values above.
  </Step>
</Steps>

<Note>
  Health reads one stack per application, the network stack. A compute,
  database or CDN stack that failed after its network stack settled still
  reports `healthy` here. Use [`fjall services <app>`](/cli/services) when you
  need per-service rollout truth.
</Note>

## Options

`fjall status` registers no options of its own. The six flags below are the
shared block Fjall registers across its commands.

| Option              | Description                                           |
| ------------------- | ----------------------------------------------------- |
| `--non-interactive` | Force plain CLI output                                |
| `-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                            |

There is no `--target`, no `--region` and no `--json`. The report always uses
the active target, and it is the same plain text with or without
`--non-interactive`, because the command has no interactive UI. `-v` adds no
extra detail to this command's output.

## Machine-readable output

`--agent` switches the report to TOON, the structured format every Fjall
command emits in agent mode. See [Agent mode](/cli/agent-mode) for the wider
contract.

```bash theme={null}
fjall status --agent
```

```
status[3]{name,health}:
  api,healthy
  web,deploying
  dashboard,not-deployed
total: 3
healthy: 1
unhealthy: 0
deploying: 1
notDeployed: 1
unknown: 0
help[2]:
  - "Run `fjall deploy <app>` to deploy"
  - "Run `fjall apps describe <app>` for details"
```

The aggregate keys carry every bucket, including the zeroes, so a consumer
never has to derive one bucket by subtracting the others.

`--fields` narrows the columns. Only `name` and `health` are selectable:

```bash theme={null}
fjall status --agent --fields name
```

```
status[3]{name}:
  api
  web
  dashboard
```

An unknown field name fails immediately with `VALIDATION_ERROR` and lists the
valid fields. The check runs before authentication and before the API query, so
a typo costs nothing.

## Exit codes

| Code | Meaning                                                                                          |
| ---- | ------------------------------------------------------------------------------------------------ |
| `0`  | The status query succeeded                                                                       |
| `1`  | The query failed: not authenticated, the named application was not found, or the API call failed |

<Warning>
  Exit `0` means the query worked, not that your applications are well. A
  report full of `unhealthy` rows still exits `0`. Do not gate a CI step on
  `fjall status`. Use [`fjall services <app>`](/cli/services), which exits
  non-zero until every ECS service has finished rolling out.
</Warning>

## Pick the right command

| Question                                      | Command                                      |
| --------------------------------------------- | -------------------------------------------- |
| Which applications are up right now?          | `fjall status`                               |
| What applications exist, and what is in one?  | [`fjall apps`](/cli/apps)                    |
| Did every ECS service finish rolling out?     | [`fjall services <app>`](/cli/services)      |
| What shipped, and how do I roll it back?      | [`fjall releases <app>`](/cli/releases)      |
| What deployments have run across the org?     | [`fjall deployments list`](/cli/deployments) |
| What resources does this application declare? | [`fjall list --app <name>`](/cli/list)       |
| What did the last codemod change in my file?  | [`fjall history --app <name>`](/cli/history) |

<Note>
  `fjall history` is unrelated to deployment history. It browses the
  `infrastructure.ts` snapshots that `fjall add`, `fjall modify` and
  `fjall remove` write locally.
</Note>

## Troubleshooting

### "Authentication required."

No usable credentials. Run [`fjall login`](/cli/login), or set `FJALL_API_KEY`
on a CI runner.

### Every application reports `unknown`

The CloudFormation probe could not read any stack. Usual causes:

* The AWS session has expired. Run [`fjall connect`](/cli/connect).
* No target is active, or the active target points at the wrong account. Check
  with [`fjall target get`](/cli/target) and set it with `fjall target set <name>`.
* AWS is throttling the CloudFormation calls. Rerun after a pause.

### `Failed to query status: Application "web" not found`

The name is not registered to your organisation. Run `fjall status` with no
argument to see the names Fjall holds.

### An application reports `healthy` but the site is down

Health reads the network stack only. Run
[`fjall services <app>`](/cli/services) for per-service rollout state, and
[`fjall drift`](/cli/drift) to find resources changed outside CloudFormation.

## Next Steps

<CardGroup cols={2}>
  <Card title="fjall services" icon="wave-square" href="/cli/services">
    Gate CI on live ECS rollout state and a non-zero exit code.
  </Card>

  <Card title="fjall releases" icon="clock-rotate-left" href="/cli/releases">
    List recorded releases and roll back to a known-good one.
  </Card>

  <Card title="fjall deployments" icon="list-checks" href="/cli/deployments">
    Inspect, cancel and force-release your organisation's deployments.
  </Card>

  <Card title="fjall deploy" icon="rocket" href="/cli/deploy">
    Ship an application after the report shows it is out of date.
  </Card>
</CardGroup>