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

# lua jobs

> List scheduled jobs, make a pushed version live, pause or resume a schedule, run a job now, and read its history

`lua jobs` manages the [jobs](/concepts/jobs) defined with `LuaJob` and pushed with `lua push job`. `deploy`, `activate`, and `deactivate` change what runs on the production schedule; `trigger` runs a job once, right now.

*Verified against lua-cli 3.33.0.*

## Synopsis

```bash theme={null}
lua jobs [view|versions|deploy|activate|deactivate|trigger|history|delete] [-i|--job-name <name>] [-v|--job-version <ver>|latest]
```

## Description

With no action the command opens a menu covering every action. Every action runs against production.

`view` lists the jobs in `lua.skill.yaml` with the server's status, schedule, last run, and next run. `-i <name>` narrows the list to one job; an unknown name exits `3`. A job that `lua.skill.yaml` lists but the server no longer has shows `Status: not found on the server`, or exits `3` with a [`lua sync`](/reference/cli/sync) hint when named with `-i`.

`versions` prints a pointer to [`lua version list`](/reference/cli/version): per-primitive history is managed by [agent versions](/concepts/releases-and-versions).

`deploy` makes one pushed version live without a confirmation prompt. It is the same operation as `lua deploy job --name <name> --set-version <ver> --force`; [`lua deploy`](/reference/cli/deploy) also records the deployed version in `lua.skill.yaml` and reports the agent version it promoted.

`activate` and `deactivate` turn the schedule on or off without changing the deployed version. A deactivated job does not run until you activate it again.

`trigger` runs the job once immediately and prints the execution ID. The schedule is unchanged. `trigger` and `delete` also resolve jobs that exist only on the server.

`history` prints the last 20 executions, newest first: status (`COMPLETED`, `FAILED`, `RUNNING`, or the server's value), start and completion times, duration, the first 100 characters of the result, and the error if any. For full execution output use [`lua logs --type job --name <name>`](/reference/cli/logs).

`delete` removes the job from the server. A job that has pushed versions is deactivated instead of deleted and stays in `lua.skill.yaml` until you remove it.

`-i` matches the job name or its ID. Every form needs a project directory and a credential.

## Arguments

| Argument | Values                                                                                 | Description               |
| -------- | -------------------------------------------------------------------------------------- | ------------------------- |
| `action` | `view`, `versions`, `deploy`, `activate`, `deactivate`, `trigger`, `history`, `delete` | Omit it to open the menu. |

Accepted spellings: `show`, `info` → `view`; `list-versions` → `versions`; `publish` → `deploy`; `on`, `enable` → `activate`; `off`, `disable` → `deactivate`; `run`, `exec`, `fire` → `trigger`; `runs`, `log` → `history`; `rm`, `remove`, `del` → `delete`.

## Options

| Option                    | Description                                                                          | Default |
| ------------------------- | ------------------------------------------------------------------------------------ | ------- |
| `-i, --job-name <name>`   | Job name or ID. Required for every action except `view`, where it filters.           | —       |
| `-v, --job-version <ver>` | Version to deploy, or `latest` for the newest pushed version. Required for `deploy`. | —       |
| `--ci`                    | Global flag. Refuse any prompt with exit `1` instead of waiting for input.           | off     |

## Examples

List the jobs with their schedule state.

```bash theme={null}
lua jobs view
```

```text Output theme={null}
============================================================
⚙️  Production Jobs
============================================================

⏰ daily-ops-report
   Job ID: 870ea1e3-fa5e-490a-82c6-ce0e480b0467
   Status: active
   Next Run: 13/09/2026, 08:00:00

⏰ health-probe
   Job ID: bcf005c0-1046-4ed9-94c7-e4af00616034
   Status: active
   Last Run: 12/09/2026, 18:07:36
   Next Run: 12/09/2026, 18:22:36

============================================================
```

Read the recent executions of one job.

```bash theme={null}
lua jobs history -i health-probe
```

```text Output theme={null}
============================================================
📊 Execution History for health-probe
============================================================

1. ✅ COMPLETED
   Execution ID: undefined
   Started: 12/09/2026, 18:07:36
   Completed: 12/09/2026, 18:07:36
   Duration: 0s
   Result: {"ok":true,"status":200,"ms":185,"at":"2026-09-12T17:07:36.309Z"}...

…
```

Run a job once from CI and read its logs.

```bash theme={null}
lua jobs trigger -i health-probe --ci
lua logs --type job --name health-probe --limit 5
```

Make the newest pushed version live from CI.

```bash theme={null}
lua jobs deploy -i health-probe -v latest --ci
```

Pause a schedule without changing the deployed version.

```bash theme={null}
lua jobs deactivate -i health-probe --ci
```

## Exit codes

| Code | Meaning     | When                                                                                                                                                                   |
| ---- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | OK          | The action completed, including a `delete` that deactivated instead.                                                                                                   |
| `1`  | Error       | The server refused the action, `-v` names a version that does not exist, or a prompt was needed under `--ci`.                                                          |
| `2`  | Usage       | Unknown action, or a required `-i` / `-v` is missing.                                                                                                                  |
| `3`  | Not found   | `-i` names a job that is not in `lua.skill.yaml` (nor on the server, for `trigger` and `delete`), the server no longer has it, or it has no pushed versions to deploy. |
| `9`  | Auth        | No valid credential.                                                                                                                                                   |
| `10` | Forbidden   | The credential cannot manage this agent.                                                                                                                               |
| `11` | Unavailable | Network error or a server 5xx.                                                                                                                                         |

The full table is in [Errors and exit codes](/reference/cli/errors-and-exit-codes).

## See also

* [`LuaJob`](/reference/sdk/luajob) — schedule types, timeout, and retry fields
* [`Jobs`](/reference/sdk/jobs) — dynamic jobs created at runtime
* [Schedule a recurring job](/build/schedule-a-job)
* [`lua deploy`](/reference/cli/deploy) — the same deploy with the agent version reported
* [`lua logs`](/reference/cli/logs) — `--type job --name <name>`