> ## Documentation Index
> Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# cron

> CLI reference: floo cron — list, show, and manually trigger scheduled cron jobs. Schedules are declared in floo.app.toml, not added by the CLI.

`floo cron` is the read-only + manual-trigger surface for scheduled cron jobs. **Cron jobs are declared in `floo.app.toml`** under `[cron.<name>]` sections — they are not created with the CLI. Every deploy reconciles the declared set: new sections become jobs, removed sections are deleted, changed sections are updated.

<Note>
  Looking for **how to add a cron job**? Edit `floo.app.toml`, not the CLI. See [Cron Jobs](/guides/cron-jobs) for the schema and end-to-end flow, or [Config Spec → `[cron.<name>]`](/reference/config-spec) for the field reference.
</Note>

## list

List every cron job declared on an app along with its enabled state, last status, and last run time.

```bash theme={null}
floo cron list --app my-app
floo cron list --app my-app --json
```

### Flags

| Flag        | Description      | Default              |
| ----------- | ---------------- | -------------------- |
| `--app APP` | App name or UUID | inferred from config |

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "cron_jobs": [
      {
        "id": "c5a1c4d8-3a36-4d4f-9d4f-3c2a1f9bb2d7",
        "name": "daily-report",
        "schedule": "0 9 * * *",
        "command": "python -m reports.daily",
        "service_name": "api",
        "timeout": 300,
        "enabled": true,
        "last_run_at": "2026-04-30T09:00:14Z",
        "last_status": "success",
        "created_at": "2026-04-12T18:00:00Z"
      }
    ]
  }
}
```

`last_run_at` and `last_status` are `null` until the first run completes. `last_status` is `success` or `failed` — the API only writes the row after the run reaches a terminal state, so there is no in-between "running" value.

***

## show

Show details for a single cron job by name.

```bash theme={null}
floo cron show daily-report --app my-app
```

### Arguments

| Argument | Description                                                             |
| -------- | ----------------------------------------------------------------------- |
| `<name>` | Cron job name — must match a `[cron.<name>]` section in `floo.app.toml` |

### Flags

| Flag        | Description      | Default              |
| ----------- | ---------------- | -------------------- |
| `--app APP` | App name or UUID | inferred from config |

### JSON output

```json theme={null}
{
  "success": true,
  "data": {
    "id": "c5a1c4d8-3a36-4d4f-9d4f-3c2a1f9bb2d7",
    "name": "daily-report",
    "schedule": "0 9 * * *",
    "command": "python -m reports.daily",
    "service_name": "api",
    "timeout": 300,
    "enabled": true,
    "last_run_at": "2026-04-30T09:00:14Z",
    "last_status": "success",
    "created_at": "2026-04-12T18:00:00Z"
  }
}
```

### Errors

| Code        | Meaning                                                                             |
| ----------- | ----------------------------------------------------------------------------------- |
| `NOT_FOUND` | No cron job with that name on this app. Run `floo cron list` to see available jobs. |

***

## run

Manually trigger a cron job by name. Useful for testing or one-off catch-up runs without waiting for the schedule.

```bash theme={null}
floo cron run daily-report --app my-app
floo cron run daily-report --app my-app --dry-run   # preview, no API call
```

### Arguments

| Argument | Description                                                             |
| -------- | ----------------------------------------------------------------------- |
| `<name>` | Cron job name — must match a `[cron.<name>]` section in `floo.app.toml` |

### Flags

| Flag        | Description                                 | Default              |
| ----------- | ------------------------------------------- | -------------------- |
| `--app APP` | App name or UUID                            | inferred from config |
| `--dry-run` | Preview the trigger without calling the API | off                  |

### What it does

1. Resolves the app from `--app` or the nearest `floo.app.toml`.
2. Calls the platform's "trigger cron job" endpoint, which dispatches a one-off Cloud Run Job execution against the service's container image.
3. Waits for the run to complete and returns the final outcome. The job's `last_run_at` and `last_status` are updated **before** the call returns, so a follow-up `floo cron list` reflects the run immediately.

***

## What the CLI does NOT do

* **Add jobs.** Edit `floo.app.toml`. The next deploy creates the job.
* **Remove jobs.** Delete the `[cron.<name>]` section from `floo.app.toml`. The next deploy deletes the job.
* **Edit schedules or commands.** Change them in `floo.app.toml`. The next deploy updates the job.

This is intentional. Schedules are stateless reconcilable resources — keeping them config-driven means the repo is the source of truth and every change ships through the same review/deploy flow as code.

## Related

* [Cron Jobs guide](/guides/cron-jobs) — long-form walkthrough with examples, schedule syntax, and the agent workflow
* [Config Spec → `[cron.<name>]`](/reference/config-spec) — full field reference
* [`floo deploys watch`](/cli/deploys) — watch a deploy reconcile cron jobs in real time