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

# Jobs Command

> Manage scheduled jobs from the CLI — view, deploy, activate, trigger, and inspect execution history

## Overview

`lua jobs` manages scheduled jobs defined with `LuaJob`. It mirrors the surfaces available for skills (view, versions, deploy, activate, deactivate, delete) and adds two job-specific actions: `trigger` (manual fire) and `history` (execution log).

```bash theme={null}
lua jobs                                  # Interactive management
lua jobs view                             # List all jobs
lua jobs versions -i myJob                # List versions for a job
lua jobs trigger -i healthCheck           # Fire a job manually
lua jobs history -i myJob                 # View execution history
```

<Note>
  For defining jobs in code, see [LuaJob API](/api/luajob). For creating jobs dynamically from inside a tool at runtime, see [Jobs API](/api/jobs).
</Note>

## Subcommands

| Action       | What it does                                                                      |
| ------------ | --------------------------------------------------------------------------------- |
| `view`       | List all jobs defined on the agent.                                               |
| `versions`   | List every version of a specific job.                                             |
| `deploy`     | Promote a version to active.                                                      |
| `activate`   | Re-enable a deactivated job.                                                      |
| `deactivate` | Pause scheduled execution. Active version retained — re-activate with `activate`. |
| `trigger`    | Manually fire a job once (does not affect schedule).                              |
| `history`    | Print recent execution history with status and timestamps.                        |
| `delete`     | Permanently remove a job and all its versions.                                    |

## Options

| Option                    | Description                                               |
| ------------------------- | --------------------------------------------------------- |
| `-i, --job-name <name>`   | Job name. Required for most non-interactive actions.      |
| `-v, --job-version <ver>` | Version for `deploy`. Pass `latest` to deploy the newest. |

## Examples

```bash theme={null}
# Interactive — pick action and target from menus
lua jobs

# List everything
lua jobs view

# Promote a specific version to active
lua jobs deploy -i dailyReport -v 1.0.3

# Promote the latest version
lua jobs deploy -i dailyReport -v latest

# Pause and resume
lua jobs deactivate -i dailyReport
lua jobs activate   -i dailyReport

# Manually trigger a job (e.g. for ad-hoc runs)
lua jobs trigger -i healthCheck

# Inspect recent runs
lua jobs history -i dailyReport

# Delete a retired job
lua jobs delete -i oldCleanupJob
```

## Triggering vs Deploying

| Command                              | When to use                                                                                                               |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `lua jobs trigger -i <name>`         | Run the job **once** right now. Useful for ad-hoc runs, smoke-tests after a deploy, and debugging. Schedule is untouched. |
| `lua jobs deploy -i <name> -v <ver>` | Promote a different version to active. Used after `lua push job` lands a new version on the server.                       |

## Common Workflow

After editing a job in code:

```bash theme={null}
lua push job             # Build + upload a new version
lua jobs versions -i myJob   # Confirm the new version is on the server
lua jobs deploy   -i myJob -v latest   # Promote it
lua jobs trigger  -i myJob   # Smoke-test the new version
lua jobs history  -i myJob   # Verify it ran cleanly
```

## Logs and Errors

To debug job execution, pair this with [`lua logs`](/cli/logs-command):

```bash theme={null}
lua logs --type job --name myJob --limit 20
lua logs --type job --name myJob --limit 20 --json | jq
```

## Related

* [LuaJob API](/api/luajob) — define a job in code
* [Jobs API](/api/jobs) — create jobs dynamically at runtime
* [Logs Command](/cli/logs-command)
* [Push & Deploy](/cli/skill-management#lua-push)