---
title: Job
description: Run batch jobs and sweeps.
canonical: 'https://lightning.ai/docs/cli/stable/command-details/job'
---
# Job {#job}

Run batch jobs and sweeps.

**Usage:**

```console
lightning job [OPTIONS] COMMAND [ARGS]...
```

## Commands {#job-commands}

| Command | Description |
| --- | --- |
| [`delete`](#job-delete) | Delete a job. |
| [`inspect`](#job-inspect) | Inspect a job for further details as JSON. |
| [`list`](#job-list) | List jobs for a given teamspace. |
| [`logs`](#job-logs) | View the logs for a job. |
| [`rename`](#job-rename) | Rename a job. |
| [`run`](#job-run) | Run async workloads using a docker image or studio. |
| [`ssh`](#job-ssh) | SSH into a running job. |
| [`stop`](#job-stop) | Stop a job. |
| [`tag`](#job-tag) | Add tags to a job. |
| [`untag`](#job-untag) | Remove tags from a job. |

## lightning job delete {#job-delete}

Delete a job.

**Usage:**

```console
lightning job delete [OPTIONS] NAME
```

### Arguments {#job-delete-arguments}

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `NAME` | `text` | yes | Job name to delete. |

### Options {#job-delete-options}

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--teamspace` | `TEXT` | no | `Sentinel.UNSET` | Override default teamspace (format: owner/teamspace). |
| `--yes`, `-y` | — | no | — | Delete without prompting for confirmation. |

## lightning job inspect {#job-inspect}

Inspect a job for further details as JSON.

**Usage:**

```console
lightning job inspect [OPTIONS] [NAME]
```

### Arguments {#job-inspect-arguments}

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `NAME` | `text` | no | Job name to inspect. |

### Options {#job-inspect-options}

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--teamspace` | `TEXT` | no | — | the name of the teamspace the job lives in. Should be specified as {teamspace\_owner}/{teamspace\_name} (e.g my-org/my-teamspace). If not specified, uses the configured default teamspace. |
| `--rank` | `INTEGER` | no | — | Inspect one machine in a multi-machine job. |
| `--json` | — | no | — | Output as JSON (inspect always emits JSON). |

## lightning job list {#job-list}

List jobs for a given teamspace.

Includes both single- and multi-machine jobs.

**Usage:**

```console
lightning job list [OPTIONS]
```

### Options {#job-list-options}

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--teamspace` | `TEXT` | no | — | the teamspace to list jobs from. Should be specified as {owner}/{name}. Defaults to the configured teamspace. |
| `--all` | — | no | — | if teamspace is not provided, list all jobs in all teamspaces. |
| `--sort-by`, `--sort_by` | `[name|teamspace|creator|status|studio|machine|image|cloud-account|started|stopped]` | no | — | the attribute to sort the jobs by. |
| `--filter` | `KEY=PATTERN` | no | `()` | Only list jobs whose KEY matches PATTERN, a case-insensitive glob. Can be a comma-separated list or passed multiple times, and every filter has to match. KEY is one of: name, teamspace, creator, status, studio, machine, image, cloud-account, started, stopped. |
| `--tags`, `--tag` | `TEXT` | no | `()` | Only list jobs carrying at least one of these tags. Can be a comma-separated list or passed multiple times. |
| `--json` | — | no | — | Output as JSON. |

### Examples {#job-list-examples}

```console
  lightning job list --filter 'name=train-*'
  lightning job list --filter 'creator=justus,status=running'
  lightning job list --all --sort-by started
```

## lightning job logs {#job-logs}

View the logs for a job.

**Usage:**

```console
lightning job logs [OPTIONS] [COMMAND] [ARGS]...
```

### Commands {#job-logs-commands}

| Command | Description |
| --- | --- |
| [`download`](#job-logs-download) | Download the complete logs for a job as a file. |

### Options {#job-logs-options}

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--teamspace` | `TEXT` | no | — | Teamspace owner/name. Uses the configured default teamspace when omitted. |
| `--follow`, `-f` | — | no | — | Stream new log lines as they are produced. |
| `--tail` | `INTEGER` | no | — | Only show the last N lines. |
| `--rank` | `INTEGER` | no | — | Machine rank to read from in a multi-machine job. |
| `--timestamps` | — | no | — | Prepend each line with its ISO-8601 timestamp. |
| `--since` | `TEXT` | no | — | Only include lines at or after this time (e.g. “2h”, RFC3339). |
| `--until` | `TEXT` | no | — | Only include lines at or before this time (e.g. “30m”, RFC3339). |
| `--query` | `TEXT` | no | — | Only include lines containing every whitespace-separated term. |
| `--severity` | `[error|warning|info|debug]` | no | — | Only include lines at or above this severity. |
| `--json` | — | no | — | Output entries as a JSON array. |
| `--interactive`, `-i` | — | no | — | Launch the interactive TUI log viewer. |

### lightning job logs download {#job-logs-download}

Download the complete logs for a job as a file.

**Usage:**

```console
lightning job logs download [OPTIONS] [NAME]
```

#### Arguments {#job-logs-download-arguments}

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `NAME` | `text` | no | The job name. Required. |

#### Options {#job-logs-download-options}

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--teamspace` | `TEXT` | no | — | Teamspace owner/name. Uses the configured default teamspace when omitted. |
| `--timestamps` | — | no | — | Prepend each line with its ISO-8601 timestamp. |

## lightning job rename {#job-rename}

Rename a job.

**Usage:**

```console
lightning job rename [OPTIONS] NAME NEW_NAME
```

### Arguments {#job-rename-arguments}

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `NAME` | `text` | yes | No description provided. |
| `NEW_NAME` | `text` | yes | No description provided. |

### Options {#job-rename-options}

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--teamspace` | `TEXT` | no | — | the name of the teamspace the job lives in. Should be specified as {teamspace\_owner}/{teamspace\_name} (e.g my-org/my-teamspace). If not specified, uses the configured default teamspace. |
| `--json` | — | no | — | Output as JSON. |

## lightning job run {#job-run}

Run async workloads using a docker image or studio.

Pass –num-machines greater than 1 to run a multi-machine job.

**Usage:**

```console
lightning job run [OPTIONS]
```

### Options {#job-run-options}

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--name` | `TEXT` | no | — | The name of the job. Needs to be unique within the teamspace. |
| `--num-machines`, `--num_machines` | `INTEGER RANGE` | no | `1` | The number of machines to run on. |
| `--machine` | `[CPU_SMALL|CPU|CPU_X_2|CPU_X_4|CPU_X_8|CPU_X_16|DATA_PREP|DATA_PREP_MAX|DATA_PREP_ULTRA|T4_SMALL|T4|T4_X_2|T4_X_4|T4_X_8|L4|L4_X_2|L4_X_4|L4_X_8|L40S|L40S_X_2|L40S_X_4|L40S_X_8|RTXP_6000|RTXP_6000_X_2|RTXP_6000_X_4|RTXP_6000_X_8|A100|A100_X_2|A100_X_4|A100_X_8|H100|H100_X_2|H100_X_4|H100_X_8|H200|H200_X_2|H200_X_4|H200_X_8|B200|B200_X_8]` | no | `'CPU'` | The machine type to run the job on. |
| `--command` | `TEXT` | no | — | The command to run inside your job. Required if using a studio. Optional if using an image. If not provided for images, will run the container entrypoint and default command. |
| `--studio` | `TEXT` | no | — | The studio env to run the job with. Mutually exclusive with image. If both –studio and –image are omitted while running inside a Studio, defaults to that Studio (if its teamspace matches –teamspace). |
| `--image` | `TEXT` | no | — | The docker image to run the job with. Mutually exclusive with studio. |
| `--teamspace` | `TEXT` | no | — | The teamspace to use, as a bare name or an ‘owner/teamspace’ slug. Defaults to the current teamspace. |
| `--org` | `TEXT` | no | — | The organization owning the teamspace (if any). Defaults to the current organization.(DEPRECATED: Pass the owner as part of –teamspace instead, e.g. ‘–teamspace owner/teamspace’. This option will be removed in a future release.) |
| `--user` | `TEXT` | no | — | The user owning the teamspace (if any). Defaults to the current user.(DEPRECATED: Pass the owner as part of –teamspace instead, e.g. ‘–teamspace owner/teamspace’. This option will be removed in a future release.) |
| `--cloud` | `TEXT` | no | — | Cloud provider or cloud account to run the job on. Defaults to the studio cloud account or teamspace default. |
| `--env`, `-e` | `TEXT` | no | `['']` | Environment variable to set inside the job. Should be of format KEY=VALUE |
| `--interruptible` | — | no | — | Whether the job should run on interruptible instances. They are cheaper but can be preempted. |
| `--image-credentials`, `--image_credentials` | `TEXT` | no | — | The credentials used to pull the image. Required if the image is private. This should be the name of the respective credentials secret created on the Lightning AI platform. |
| `--cloud-account-auth`, `--cloud_account_auth` | — | no | — | Whether to authenticate with the cloud account to pull the image. Required if the registry is part of a cloud provider (e.g. ECR). |
| `--entrypoint` | `TEXT` | no | — | The entrypoint of your docker container. Default runs the provided command in a standard shell. To use the pre-defined entrypoint of the provided image, set this to an empty string. Only applicable when submitting docker jobs. |
| `--path-mapping`, `--path_mapping` | `TEXT` | no | `['']` | Maps path inside of containers to paths inside data-connections. Should be of form <CONTAINER\_PATH\_1>:<CONNECTION\_NAME\_1>:<PATH\_WITHIN\_CONNECTION\_1> and omitting the path inside the connection defaults to the connections root. Can be specified multiple times for multiple mappings |
| `--path-mappings`, `--path_mappings` | `TEXT` | no | `''` | Maps path inside of containers to paths inside data-connections. Should be a comma separated list of form: <MAPPING\_1>,<MAPPING\_2>,… where each mapping is of the form <CONTAINER\_PATH\_1>:<CONNECTION\_NAME\_1>:<PATH\_WITHIN\_CONNECTION\_1> and omitting the path inside the connection defaults to the connections root. Instead of a comma-separated list, consider passing –path-mapping multiple times. |
| `--tags`, `--tag` | `TEXT` | no | `()` | Tag to apply to the job. Can be a comma-separated list or passed multiple times. Tags that don’t exist in the teamspace yet are created. |
| `--json` | — | no | — | Output the created job as JSON. |
| `--keep-minutes`, `--keep_minutes` | `INTEGER RANGE` | no | — | Minutes to keep the machine after the job stops. Omit or pass 0 to release the machine immediately. |

## lightning job ssh {#job-ssh}

SSH into a running job.

**Usage:**

```console
lightning job ssh [OPTIONS] NAME
```

### Arguments {#job-ssh-arguments}

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `NAME` | `text` | yes | No description provided. |

### Options {#job-ssh-options}

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--teamspace` | `TEXT` | no | — | the name of the teamspace the job lives in. Should be specified as {teamspace\_owner}/{teamspace\_name} (e.g my-org/my-teamspace). If not specified, uses the configured default teamspace. |
| `--rank` | `INTEGER` | no | — | Machine rank for a multi-machine job. Defaults to 0. |

### Examples {#job-ssh-examples}

```console
  lightning job ssh my-job
```

## lightning job stop {#job-stop}

Stop a job.

**Usage:**

```console
lightning job stop [OPTIONS] NAME
```

### Arguments {#job-stop-arguments}

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `NAME` | `text` | yes | Job name to stop. |

### Options {#job-stop-options}

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--teamspace` | `TEXT` | no | — | the name of the teamspace the job lives in. Should be specified as {teamspace\_owner}/{teamspace\_name} (e.g my-org/my-teamspace). If not specified, uses the configured default teamspace. |
| `--json` | — | no | — | Output as JSON. |

## lightning job tag {#job-tag}

Add tags to a job.

Adding a tag that already exists on the job is a no-op for that tag.

> lightning job tag my-job prod gpu

**Usage:**

```console
lightning job tag [OPTIONS] NAME TAGS...
```

### Arguments {#job-tag-arguments}

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `NAME` | `text` | yes | No description provided. |
| `TAGS` | `text` | yes | No description provided. |

### Options {#job-tag-options}

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--teamspace` | `TEXT` | no | — | the name of the teamspace the job lives in. Should be specified as {teamspace\_owner}/{teamspace\_name} (e.g my-org/my-teamspace). If not specified, uses the configured default teamspace. |
| `--json` | — | no | — | Output as JSON. |

## lightning job untag {#job-untag}

Remove tags from a job.

Removing a tag not present on the job is a no-op for that tag.

> lightning job untag my-job prod

**Usage:**

```console
lightning job untag [OPTIONS] NAME TAGS...
```

### Arguments {#job-untag-arguments}

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `NAME` | `text` | yes | No description provided. |
| `TAGS` | `text` | yes | No description provided. |

### Options {#job-untag-options}

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--teamspace` | `TEXT` | no | — | the name of the teamspace the job lives in. Should be specified as {teamspace\_owner}/{teamspace\_name} (e.g my-org/my-teamspace). If not specified, uses the configured default teamspace. |
| `--json` | — | no | — | Output as JSON. |

---

**Navigation**

- Parent: [Command details](/docs/cli/2026.11.04/command-details.md)