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

> Diagnose and repair local Fjall CLI state, and clear leaked CDK synth temp directories from your machine.

<Accordion title="Prerequisites">
  | Requirement    | Detail                                              |
  | -------------- | --------------------------------------------------- |
  | Fjall CLI      | Installed and on your `PATH`                        |
  | Node.js        | 22 or later                                         |
  | Login          | Not required. `fjall doctor` reads local state only |
  | AWS connection | Not required. The command makes no AWS calls        |
</Accordion>

## Diagnose CLI state

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

`fjall doctor` takes no arguments and has no subcommands.

```bash theme={null}
# Report leaked CDK synth temp dirs
fjall doctor

# Preview what a clean-up would delete
fjall doctor --clean-cdk-tmpdir --dry-run

# Preview with the path and size of every directory
fjall doctor --clean-cdk-tmpdir --dry-run --verbose

# Remove leaked temp dirs older than 24 hours
fjall doctor --clean-cdk-tmpdir

# Widen the sweep to anything older than one hour
fjall doctor --clean-cdk-tmpdir --max-age-hours 1
```

## What Happens

Every in-process CDK synth that runs without an explicit output directory leaves one `cdk.out*` directory behind in `$TMPDIR`. Those directories accumulate and can reach several gigabytes on a machine that synthesises often.

`fjall doctor` scans `$TMPDIR` for directories whose name starts with `cdk.out`, keeps the ones last modified more than 24 hours ago, and totals their size on disk.

### Default run (read-only)

The default run deletes nothing. With nothing stale to report:

```
All checks passed.
```

With stale directories present:

```
3 stale cdk.out* temp dirs in $TMPDIR (412.6 MB).
  Run 'fjall doctor --clean-cdk-tmpdir' to remove them.
```

### Clean-up run

`--clean-cdk-tmpdir` deletes the directories it finds:

```
Removing 3 cdk.out* temp dirs (412.6 MB)...
Removed 3 dirs (412.6 MB reclaimed).
```

Directories that cannot be removed are counted in the summary rather than failing the command:

```
Removed 2 dirs (275.1 MB reclaimed), 1 failed.
```

When nothing matches the age threshold, the command prints `No stale cdk.out* temp dirs found.` and exits.

<Warning>
  Removal is permanent and recursive. Run `--dry-run` first if you want to see the list before anything is deleted.
</Warning>

### Dry-run behaviour

`--dry-run` applies only alongside `--clean-cdk-tmpdir`. It prints the count and total size, then exits without deleting:

```
Would remove 3 cdk.out* temp dirs (412.6 MB).
```

Add `-v, --verbose` to list each directory:

```
Would remove 3 cdk.out* temp dirs (412.6 MB).
  /var/folders/9x/T/cdk.outA1b2C3 (137.5 MB)
  /var/folders/9x/T/cdk.outD4e5F6 (145.2 MB)
  /var/folders/9x/T/cdk.outG7h8I9 (129.9 MB)
```

`-v, --verbose` affects the dry-run listing only. The other paths print their summary regardless.

### Age threshold

`--max-age-hours <n>` overrides the 24-hour threshold used by `--clean-cdk-tmpdir`. The read-only diagnostic pass always uses 24 hours, so `--max-age-hours` on its own changes nothing.

### Agent mode

`fjall doctor` is a human-only surface with no machine-readable output. Passing `--agent`, `--fields`, `--budget` or `--full` returns a validation error and the command does not run. Agent mode detected from the environment does not trigger that refusal, so a bare `fjall doctor` behaves the same inside an agent session as it does in a terminal.

## Options

| Flag                  | Description                                                            | Default          |
| --------------------- | ---------------------------------------------------------------------- | ---------------- |
| `--clean-cdk-tmpdir`  | Remove leaked CDK synth temp dirs from `$TMPDIR` (>24h old by default) | Off, report only |
| `--max-age-hours <n>` | Override the age threshold for `--clean-cdk-tmpdir` (hours)            | `24`             |
| `--dry-run`           | Print what would be removed without deleting                           | Off              |
| `--non-interactive`   | Force plain CLI output (no UI)                                         | Off              |
| `-v, --verbose`       | Enable verbose output                                                  | Off              |

## Next Steps

<CardGroup cols={2}>
  <Card title="fjall validate" icon="circle-check" href="/cli/validate">
    Check an application's infrastructure, including a local CloudFormation synth with `--deep --synth`.
  </Card>

  <Card title="fjall drift" icon="radar" href="/cli/drift">
    Detect and repair differences between your definitions and deployed AWS resources.
  </Card>

  <Card title="fjall deploy" icon="rocket" href="/cli/deploy">
    Deploy an application to AWS once local state is clean.
  </Card>

  <Card title="fjall login" icon="key" href="/cli/login">
    Sign in to Fjall and store credentials in `~/.fjall/auth.json` (or `$FJALL_CONFIG_DIR/auth.json`).
  </Card>
</CardGroup>