---
# Generated by kapten-docs from the CLI's command tree. DO NOT EDIT.
title: "kapten jobs"
description: "Run and schedule jobs."
sidebar:
  label: "jobs"
---

Every command takes the [global flags](/cli/reference#global-flags).

## kapten jobs create

Creates a cron or one-off job in an environment.

```bash
kapten jobs create <project-id> <environment-id> <body...> [flags]
```

| Argument | Description |
| --- | --- |
| `project-id` | The unique identifier for the project |
| `environment-id` | The unique identifier of the environment |
| `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). |

| Flag | Description |
| --- | --- |
| `--rsh-generate-body` | Print an example request body and exit |
| `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending |

Request body fields, `*` for required:

```text
{
  configuration*: {
    arguments: [
      (string)
    ]
    cpu_limit_in_milli: (string) Maximum cpu that can be allocated to the job based on organization cluster configuration. unit is millicores (m). 1000m = 1 cpu
    cpu_request_in_milli: (string) unit is millicores (m). 1000m = 1 cpu
    default_port: (integer default:<nil> min:1) Port where to run readiness and liveliness probes checks. The port will not be exposed externally
    entrypoint: (string) Container entrypoint
    healthchecks*: {
      liveness_probe: {
        failure_threshold: (integer default:9)
        initial_delay_seconds: (integer default:30)
        period_seconds: (integer default:10)
        success_threshold: (integer default:1)
        timeout_seconds: (integer default:5)
        type: {
          exec: <...>
          grpc: <...>
          http: <...>
          tcp: <...>
        }
      }
      readiness_probe: {
        failure_threshold: (integer default:9)
        initial_delay_seconds: (integer default:30)
        period_seconds: (integer default:10)
        success_threshold: (integer default:1)
        timeout_seconds: (integer default:5)
        type: {
          exec: <...>
          grpc: <...>
          http: <...>
          tcp: <...>
        }
      }
    }
    max_duration_seconds: (integer min:0) Maximum number of seconds allowed for the job to run before killing it and mark it as failed
    max_nb_restart: (integer min:0) Maximum number of restart allowed before the job is considered as failed 0 means that no restart/crash of the job is allowed
    ram_limit_in_mib: (string) Maximum memory that can be allocated to the job based on organization cluster configuration. unit is MB. 1024 MB = 1GB
    ram_request_in_mib: (string) unit is MB. 1024 MB = 1GB
    source: oneOf{
      {
        image_name*: (string pattern:\S minLen:1) image name
        tag*: (string pattern:\S minLen:1) tag of the image container
      }
    }
  }
  cron: (string format:cron) Specifies the job schedule using standard cron format (minute hour day month weekday). Does not include seconds field - follows the traditional 5-field cron syntax.
  description: (string)
  name*: (string pattern:\S minLen:1) Name of the job
  timezone: (string format:timezone) Specifies the timezone for the cron job. Defaults to UTC.
}
```

Example:

```bash
kapten jobs create <project-id> <environment-id> <input.json
```

## kapten jobs deploy

Starts a deployment of the job.

```bash
kapten jobs deploy <project-id> <environment-id> <job-id> [flags]
```

| Argument | Description |
| --- | --- |
| `project-id` | The unique identifier for the project |
| `environment-id` | The unique identifier of the environment |
| `job-id` | The unique identifier for the job |

Example:

```bash
kapten jobs deploy <project-id> <environment-id> <job-id>
```

## kapten jobs get

Returns a job.

```bash
kapten jobs get <project-id> <environment-id> <job-id> [flags]
```

| Argument | Description |
| --- | --- |
| `project-id` | The unique identifier for the project |
| `environment-id` | The unique identifier of the environment |
| `job-id` | The unique identifier for the job |

Example:

```bash
kapten jobs get <project-id> <environment-id> <job-id>
```

## kapten jobs get-run

Returns one deployment run of the job.

```bash
kapten jobs get-run <project-id> <environment-id> <job-id> <component-run-id> [flags]
```

| Argument | Description |
| --- | --- |
| `project-id` | The unique identifier for the project |
| `environment-id` | The unique identifier of the environment |
| `job-id` | The unique identifier for the job |
| `component-run-id` | The unique identifier for the component run |

Example:

```bash
kapten jobs get-run <project-id> <environment-id> <job-id> <component-run-id>
```

## kapten jobs list-runs

Returns the job's deployment runs, a page at a time.

```bash
kapten jobs list-runs <project-id> <environment-id> <job-id> [flags]
```

| Argument | Description |
| --- | --- |
| `project-id` | The unique identifier for the project |
| `environment-id` | The unique identifier of the environment |
| `job-id` | The unique identifier for the job |

| Flag | Description |
| --- | --- |
| `--action string` | Filter component runs by action. |
| `--created-after string` | Filter component runs created at or after this timestamp. |
| `--created-before string` | Filter component runs created at or before this timestamp. |
| `--page-limit int` | Maximum number of records to return (default: 10) |
| `--page-number int` | Page number (default: 1) |
| `--status string` | Filter component runs by deployment status. |
| `--trigger string` | Filter component runs by trigger source. |

Example:

```bash
kapten jobs list-runs <project-id> <environment-id> <job-id>
```

## kapten jobs query-run-logs

Returns the deployment logs of one job run: what Kapten did while deploying it, and what its agent on the cluster did. For the job's own output, use the component logs.

Without `from` or `to`, the window spans the run, from its start to its end. Logs follow the retention of the log backend, so the logs of an old run may be gone, and runs from before run logs existed return an empty list.

```bash
kapten jobs query-run-logs <project-id> <environment-id> <job-id> <component-run-id> <body...> [flags]
```

| Argument | Description |
| --- | --- |
| `project-id` | The unique identifier for the project |
| `environment-id` | The unique identifier of the environment |
| `job-id` | The unique identifier for the job |
| `component-run-id` | The unique identifier for the component run |
| `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). |

| Flag | Description |
| --- | --- |
| `--rsh-generate-body` | Print an example request body and exit |
| `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending |

Request body fields, `*` for required:

```text
{
  from: (string format:date-time) Inclusive lower bound for the run log time range.
  levels: [
    (string)
  ]
  limit: (integer format:int32 default:200 min:1 max:1000) Maximum number of most recent raw backend records to query.
  source: [
    (string enum:control_plane,agent,builder)
  ]
  text: (string) Optional phrase to search in the log message.
  to: (string format:date-time) Inclusive upper bound for the run log time range.
  view: (string default:both enum:timeline,raw,both) Which run log projection to return.
}
```

Example:

```bash
kapten jobs query-run-logs <project-id> <environment-id> <job-id> <component-run-id> 'limit: 200, source: [control_plane, agent], view: timeline'
```

## kapten jobs update

Updates a job. Fields left out keep their value.

```bash
kapten jobs update <project-id> <environment-id> <job-id> <body...> [flags]
```

| Argument | Description |
| --- | --- |
| `project-id` | The unique identifier for the project |
| `environment-id` | The unique identifier of the environment |
| `job-id` | The unique identifier for the job |
| `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). |

| Flag | Description |
| --- | --- |
| `--rsh-generate-body` | Print an example request body and exit |
| `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending |

Request body fields, `*` for required:

```text
{
  configuration: {
    arguments: [
      (string)
    ]
    cpu_limit_in_milli: (string) Updated CPU limit.
    cpu_request_in_milli: (string) Updated CPU request.
    default_port: (integer min:1) Updated default probe port.
    entrypoint: (string) Updated container entrypoint.
    healthchecks: {
      liveness_probe: {
        failure_threshold: (integer default:9)
        initial_delay_seconds: (integer default:30)
        period_seconds: (integer default:10)
        success_threshold: (integer default:1)
        timeout_seconds: (integer default:5)
        type: {
          exec: <...>
          grpc: <...>
          http: <...>
          tcp: <...>
        }
      }
      readiness_probe: {
        failure_threshold: (integer default:9)
        initial_delay_seconds: (integer default:30)
        period_seconds: (integer default:10)
        success_threshold: (integer default:1)
        timeout_seconds: (integer default:5)
        type: {
          exec: <...>
          grpc: <...>
          http: <...>
          tcp: <...>
        }
      }
    }
    max_duration_seconds: (integer min:0) Updated max duration in seconds.
    max_nb_restart: (integer min:0) Updated restart limit.
    ram_limit_in_mib: (string) Updated RAM limit.
    ram_request_in_mib: (string) Updated RAM request.
    source: oneOf{
      {
        image_name*: (string pattern:\S minLen:1) image name
        tag*: (string pattern:\S minLen:1) tag of the image container
      }
    }
  }
  cron: (string format:cron) Updated cron schedule.
  description: (string) Updated job description.
  name: (string pattern:\S minLen:1) Updated job name.
  timezone: (string format:timezone) Updated cron timezone.
  type: allOf{
    (string enum:cron,one_time) Job scheduling strategy.
  }
}
```

Example:

```bash
kapten jobs update <project-id> <environment-id> <job-id> <input.json
```
