> ## 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 costs
> View AWS cost summaries, forecasts and per-service breakdowns for your Fjall organisation from the command line.
`fjall costs` reads AWS spend for the signed-in organisation from the Fjall control plane.
The command is a read-only query. It deploys nothing, and it makes no AWS call from your machine.
* Fjall CLI installed on Node 22 or later.
* Signed in with `fjall login`, or `FJALL_API_KEY` exported for headless use. Credentials live in `~/.fjall/auth.json` (or `$FJALL_CONFIG_DIR/auth.json`).
* At least one AWS account connected with `fjall connect`.
* Cost Explorer enabled in the management account. Fjall collects spend through the AWS Cost Explorer API, so a newly connected organisation returns empty results until collection has run.
Without usable credentials the command exits with `Authentication required. Run 'fjall login' first.`
## View cost data
```bash theme={null}
fjall costs [subcommand] [options]
```
`show` is the only subcommand and it is also the default, so `fjall costs` and `fjall costs show` do the same thing.
```bash theme={null}
# Last 30 days: total spend plus a per-service split
fjall costs
# Daily trend for the last 14 days, with a previous-period comparison
fjall costs show --mode trend --days 14
# Project the next 14 days from 60 days of history
fjall costs --mode forecast --days 60 --forecast-days 14
# Month-to-date total for the whole organisation
fjall costs --mode month_to_date
# Cost per request for one application, over the last 14 days
fjall costs --mode per_request -a cm7x2q0180000ab12cd34ef56 --days 14
```
`-a, --app` is forwarded to the API as `applicationId`, and the cost tables are keyed by application ID. Read the ID from the `ID:` line of `fjall apps describe api`.
## Modes
`--mode` selects what the API returns. The default is `summary`.
| Mode | Returns | Notes |
| ---------------- | --------------------------------------------------------------------------------- | -------------------------------- |
| `summary` | Total spend plus a by-service split over the window | Default mode |
| `trend` | Daily spend with a previous-period comparison | Window set by `--days` |
| `forecast` | Linear-regression projection of future spend | Horizon set by `--forecast-days` |
| `attribution` | Per-service breakdown of spend | Window set by `--days` |
| `per_request` | Daily spend divided by request count for one application | Requires `-a` |
| `per_deployment` | Daily spend divided by deployment count for one application | Requires `-a` |
| `month_to_date` | Month-to-date total, or the application's month-to-date amount when `-a` is given | Ignores `--days` |
`per_request` and `per_deployment` without `-a` return `400` with `applicationId is required for per_request mode`.
The CLI forwards `--mode` without validating it locally. `fjall costs --help` still lists `breakdown`, which the API rejects with `400 Invalid query parameters`. Use `attribution` for a per-service breakdown.
## What Happens
1. The CLI checks the stored credentials and stops if none are usable.
2. It calls `GET /api/costs`, passing `mode`, `days`, `forecastDays` and `applicationId` as query parameters when set.
3. The control plane reads the collected cost records for your organisation and returns the result for that mode.
4. The CLI prints a `==> Fetching cost data` step line, the JSON response, then a completion summary.
Nothing is written, so the command has no dry-run flag, no confirmation prompt and no rollback path.
**Agent mode.** With `--agent` (or on an auto-detected agent host) the same payload renders as a TOON block instead of JSON. `--budget` trims that block. `--fields` has no effect on `costs show`, because the handler renders the API response unshaped.
**Rate limit.** The API accepts 30 cost queries per minute per organisation. Beyond that it returns `429` with `Too many cost query requests. Please try again later.`
**Unknown subcommands.** Anything other than `show` fails with `Error: Unknown subcommand ''` followed by `Available subcommands: show`.
## Options
| Flag | Description | Default |
| --------------------- | --------------------------------------------------------------- | ------------------------ |
| `--mode ` | Cost view mode. See [Modes](#modes) for accepted values. | `summary` |
| `--days ` | Days of history to include. Whole number, 1 to 90. | `30`, applied by the API |
| `--forecast-days ` | Days to forecast (`mode=forecast` only). Whole number, 1 to 30. | `7`, applied by the API |
| `-a, --app ` | Filter by application. Pass the application ID. | All applications |
| `--agent` | Enable agent output mode. | Auto-detected |
| `--budget ` | Output budget: minimal, compact, or token count. | Unset |
| `--fields ` | Select exactly these output fields. | Unset |
| `--full` | Disable content truncation. | Off |
| `--non-interactive` | Force plain CLI output (no UI). | Off |
| `-v, --verbose` | Enable verbose output. | Off |
Values outside the accepted ranges for `--days` and `--forecast-days` are rejected by the API with `400 Invalid query parameters`.
## Next Steps
Turn on the AWS Cost Explorer API so Fjall can collect spend data.
Connect an AWS account so its spend appears in cost queries.
Deploy an application, then track what it costs.
Read cost data as TOON blocks from an AI agent session.