Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

fjall metrics reads application performance metrics from the Fjall control plane. It calls GET /api/app-metrics and prints the rows. It never calls AWS directly.

Prerequisites

Requirement	How to satisfy it
Authenticated CLI	Run `fjall login`, or set `FJALL_API_KEY` for CI. Credentials live at `~/.fjall/auth.json` (or `$FJALL_CONFIG_DIR/auth.json`).
Token with `read` scope	Personal tokens from `fjall token create` and CI tokens minted in the web app under Settings, CI/CD Tokens both carry scopes. The route rejects a token without `read`.
At least one application	Metrics rows are keyed by application. Create one with `fjall create application` and deploy it with `fjall deploy <app>`.
Node 22 or later	The `fjall` package declares `"node": ">=22.0.0"`.

Metrics come from Fjall’s monitoring pipeline, so an application that has never been deployed returns no rows.

View application metrics

fjall metrics [subcommand] [options]

show is the only subcommand, and it is also the fallback when the positional is omitted. fjall metrics and fjall metrics show run the same code path.

# Current sample for every application in the organisation
fjall metrics show --mode latest

# Hourly request, error and latency buckets for the last 24 hours
fjall metrics show --mode sparklines --hours 24

# Every sample across the organisation for the last week
fjall metrics show --mode org_summary --hours 168 --limit 500

Any other positional is rejected:

Error: Unknown subcommand 'requests'
Available subcommands: show

metrics show

fjall metrics show [options]

--mode selects which query runs on the server. The four accepted values behave differently:

Mode	Returns	Uses `--app`	Uses `--hours`	Uses `--limit`
`latest`	The most recent sample per application, taken from a fixed 48 hour window	Optional filter	No	No
`time_series`	Per-sample rows for one application, oldest first	Required	Yes	Yes
`sparklines`	Hourly request, error and latency buckets per application	Optional filter	Yes	No
`org_summary`	Every sample across the organisation, newest first	No	Yes	Yes

The CLI forwards --mode to the metrics API unchanged, and the API accepts only time_series, latest, sparklines and org_summary. The values printed in fjall metrics --help (summary, requests, errors, latency) and the CLI default of summary are rejected by the API with 400 Invalid query parameters. Pass one of the four API modes explicitly on every invocation.

-a, --app <name> is sent verbatim as the applicationId query parameter. The server treats it as an application ID, not a name. Read the ID from fjall apps describe <app>, which returns name, health and id.

# Read the application id for the `api` app
fjall apps describe api

# Per-sample series for that application over the last 6 hours
fjall metrics show --mode time_series --app cm4x9j1of0003abcd7q2wlp8z --hours 6 --limit 200

time_series without --app returns 400 applicationId is required for time_series mode.

What Happens

The CLI checks stored credentials. Missing or rejected credentials stop the command with Authentication required. before any request goes out.
The subcommand resolves to show, and any unrecognised positional exits with the unknown-subcommand error above.
The CLI issues GET /api/app-metrics with mode, applicationId, hours and limit as query parameters. Absent flags are omitted from the query string, and the server applies its own defaults.
On success, the CLI prints the response as pretty-printed JSON on stdout. Every string is passed through credential masking first.
On failure, the CLI prints Error: <message> on stderr and exits non-zero.

The command is read-only. It creates nothing, changes nothing, and has no dry-run mode.

Output shapes

The response body is a bare array of rows, with no envelope. time_series, latest and org_summary return metric rows carrying application_id, resource_name, resource_type, timestamp, cpu_utilisation, memory_utilisation, request_count, error_count, target_response_time, error_rate, health_status and the per-service counters for databases, storage, Lambda, queues, cache, DynamoDB and CDN. sparklines returns application_id, hour, requests, errors and response_time_ms. target_response_time is recorded in seconds. Multiply by 1000 to compare it against millisecond latency figures.

Agent mode

With --agent, or on an auto-detected agent host, the result renders as a TOON block on stdout instead of JSON, and failures render as a structured TOON error block rather than a stderr line. --no-agent forces the human path. metrics show renders its payload without a field schema, so --budget and --full shape the block while --fields is accepted and has no effect on the rows. Filter the JSON with jq when you want a subset.

Scale and failure responses

Condition	Response
More than 60 requests per minute for one organisation	`429` with `Retry-After: 60`
Metrics store unreadable	`503 Could not read metrics (<cause>)`, so a broken read never reads as “no traffic”
Organisation has no applications, `latest` or `sparklines`	`[]`
No `--app` filter	`latest` and `sparklines` cover the first 100 applications in the organisation

Options

Flag	Description	Default
`--mode <mode>`	Metrics view mode. Help text reads `summary \| requests \| errors \| latency`, the API accepts `time_series \| latest \| sparklines \| org_summary`	`summary` (rejected by the API)
`-a, --app <name>`	Filter by application. Sent as `applicationId`, so pass the ID	None, all applications
`--hours <n>`	Hours of history to include. Parsed as a decimal integer, server range 1 to 168	`24`
`--limit <n>`	Max rows to return. Parsed as a decimal integer, server range 1 to 500	`100`
`--non-interactive`	Force plain CLI output (no UI)	Off
`-v, --verbose`	Enable verbose output	Off
`--agent`	Enable agent output mode	Auto-detected
`--budget <level>`	Output budget: minimal, compact, or token count	None
`--fields <fields>`	Select exactly these output fields. No effect on `metrics show`, which renders without a field schema	All fields
`--full`	Disable content truncation	Off

--agent, --no-agent, --budget, --fields, --full, --non-interactive and -v, --verbose are also root-level options, so fjall --agent metrics show --mode latest works too.

Next Steps

fjall deploy

Ship a new version of the application whose metrics you just read.

fjall releases

Correlate a metric change with the release that landed.

fjall drift

Detect and repair infrastructure that has moved away from your definition.

Agent mode

Read metrics as TOON blocks from an AI agent or a script.

Core Commands

Infrastructure Codemods

Insights

Management Commands

Build & CI

Environments & Data

Diagnostics & Recovery

Authentication

Agent Mode

fjall metrics

View application metrics

metrics show

What Happens

Output shapes

Agent mode

Scale and failure responses

Options

Next Steps

fjall deploy

fjall releases

fjall drift

Agent mode

​View application metrics

​metrics show

​What Happens

​Output shapes

​Agent mode

​Scale and failure responses

​Options

​Next Steps

fjall deploy

fjall releases

fjall drift

Agent mode

View application metrics

metrics show

What Happens

Output shapes

Agent mode

Scale and failure responses

Options

Next Steps