# Documentation for `scw jobs`


:::note{title="The CLI documentation pages are currently under construction"}
The content is up to date. We're making improvements to the site over the next few weeks for a better experience.
:::

<!-- DO NOT EDIT: this file is automatically generated using scw-doc-gen -->
This API allows you to manage your Serverless Jobs.

- [](#)
  - [Create a new job definition in a specified Project](#create-a-new-job-definition-in-a-specified-project)
  - [Delete an existing job definition by its unique identifier](#delete-an-existing-job-definition-by-its-unique-identifier)
  - [Get a job definition by its unique identifier](#get-a-job-definition-by-its-unique-identifier)
  - [List all your job definitions with filters](#list-all-your-job-definitions-with-filters)
  - [Run an existing job definition using its unique identifier and create a new job run](#run-an-existing-job-definition-using-its-unique-identifier-and-create-a-new-job-run)
  - [Update an existing job definition associated with the specified unique identifier](#update-an-existing-job-definition-associated-with-the-specified-unique-identifier)
- [](#)
  - [Get a job run by its unique identifier](#get-a-job-run-by-its-unique-identifier)
  - [List all job runs with filters](#list-all-job-runs-with-filters)
  - [Stop a job run using its unique identifier](#stop-a-job-run-using-its-unique-identifier)
  - [Wait for a job run to reach a stable state](#wait-for-a-job-run-to-reach-a-stable-state)
- [](#)
  - [Create a secret reference within a job definition](#create-a-secret-reference-within-a-job-definition)
  - [Delete a secret reference within a job definition](#delete-a-secret-reference-within-a-job-definition)
  - [Get a secret references within a job definition](#get-a-secret-references-within-a-job-definition)
  - [List secrets references within a job definition](#list-secrets-references-within-a-job-definition)
  - [Update a secret reference within a job definition](#update-a-secret-reference-within-a-job-definition)
- [](#)
  - [Create a trigger](#create-a-trigger)
  - [Delete a trigger](#delete-a-trigger)
  - [Get a trigger](#get-a-trigger)
  - [List triggers of a job definition](#list-triggers-of-a-job-definition)
  - [Update a trigger](#update-a-trigger)


## 




### Create a new job definition in a specified Project

Create a new job definition in a specified Project.

**Usage:**

```shell
scw jobs definition create [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| name | Required<br />Default: `<generated>` | Name of the job definition |
| cpu-limit | Required | CPU limit of the job (in mvCPU) |
| memory-limit | Required | Memory limit of the job (in MiB) |
| local-storage-capacity |  | Local storage capacity of the job (in MiB) |
| image-uri | Required | Image to use for the job |
| ~~command~~ | Deprecated | Startup command. If empty or not defined, the image's default command is used. |
| startup-command.{index} |  | Job startup command. Overrides the default defined in the job image. |
| args.{index} |  | Job arguments. Overrides the default arguments defined in the job image. |
| project-id |  | Project ID to use. If none is passed the default project ID will be used |
| environment-variables.{key} |  | Environment variables of the job |
| description |  | Description of the job |
| job-timeout |  | Timeout of the job in seconds |
| cron-schedule.schedule |  |  |
| cron-schedule.timezone |  |  |
| retry-policy.max-retries |  | Maximum number of retries upon a job failure. |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



### Delete an existing job definition by its unique identifier

Delete an existing job definition by its unique identifier.

**Usage:**

```shell
scw jobs definition delete <job-definition-id ...> [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| job-definition-id | Required | UUID of the job definition to delete |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



### Get a job definition by its unique identifier

Get a job definition by its unique identifier.

**Usage:**

```shell
scw jobs definition get <job-definition-id ...> [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| job-definition-id | Required | UUID of the job definition to get |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



### List all your job definitions with filters

List all your job definitions with filters.

**Usage:**

```shell
scw jobs definition list [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| order-by | One of: `created_at_asc`, `created_at_desc` |  |
| project-id |  |  |
| organization-id |  |  |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw`, `all` | Region to target. If none is passed will use default region from the config |



### Run an existing job definition using its unique identifier and create a new job run

Run an existing job definition using its unique identifier and create a new job run.

**Usage:**

```shell
scw jobs definition start <job-definition-id ...> [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| job-definition-id | Required | UUID of the job definition to start |
| ~~command~~ | Deprecated | Contextual startup command for this specific job run. |
| startup-command.{index} |  | Contextual startup command for this specific job run. |
| args.{index} |  | Contextual arguments for this specific job run. |
| environment-variables.{key} |  | Contextual environment variables for this specific job run |
| replicas |  | Number of jobs to run |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



### Update an existing job definition associated with the specified unique identifier

Update an existing job definition associated with the specified unique identifier.

**Usage:**

```shell
scw jobs definition update <job-definition-id ...> [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| job-definition-id | Required | UUID of the job definition to update |
| name |  | Name of the job definition |
| cpu-limit |  | CPU limit of the job (in mvCPU) |
| memory-limit |  | Memory limit of the job (in MiB) |
| local-storage-capacity |  | Local storage capacity of the job (in MiB) |
| image-uri |  | Image to use for the job |
| ~~command~~ | Deprecated | Startup command. If empty or not defined, the image's default command is used. |
| startup-command.{index} |  | Job startup command. Overrides the default defined in the job image. |
| args.{index} |  | Job arguments. Overrides the default arguments defined in the job image. |
| environment-variables.{key} |  | Environment variables of the job |
| description |  | Description of the job |
| job-timeout |  | Timeout of the job in seconds |
| cron-schedule.schedule |  |  |
| cron-schedule.timezone |  |  |
| retry-policy.max-retries |  |  |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



## 




### Get a job run by its unique identifier

Get a job run by its unique identifier.

**Usage:**

```shell
scw jobs run get <job-run-id ...> [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| job-run-id | Required | UUID of the job run to get |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



### List all job runs with filters

List all job runs with filters.

**Usage:**

```shell
scw jobs run list [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| order-by | One of: `created_at_asc`, `created_at_desc` |  |
| job-definition-id |  |  |
| project-id |  |  |
| state | One of: `unknown_state`, `initialized`, `validated`, `queued`, `running`, `succeeded`, `failed`, `interrupting`, `interrupted`, `retrying` |  |
| states.{index} | One of: `unknown_state`, `initialized`, `validated`, `queued`, `running`, `succeeded`, `failed`, `interrupting`, `interrupted`, `retrying` |  |
| reasons.{index} | One of: `unknown_reason`, `invalid_request`, `timeout`, `cancellation`, `technical_error`, `image_not_found`, `invalid_image`, `memory_usage_exceeded`, `storage_usage_exceeded`, `exited_with_error`, `secret_disabled`, `secret_not_found`, `quota_exceeded` |  |
| organization-id |  |  |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw`, `all` | Region to target. If none is passed will use default region from the config |



### Stop a job run using its unique identifier

Stop a job run using its unique identifier.

**Usage:**

```shell
scw jobs run stop [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| job-run-id | Required | UUID of the job run to stop |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



### Wait for a job run to reach a stable state

Wait for a job run to reach a stable state. This is similar to using --wait flag.

**Usage:**

```shell
scw jobs run wait <job-run-id ...> [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| job-run-id | Required |  |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



## 




### Create a secret reference within a job definition

Create a secret reference within a job definition.

**Usage:**

```shell
scw jobs secret create [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| job-definition-id | Required | UUID of the job definition |
| secrets.{index}.secret-manager-id |  |  |
| secrets.{index}.secret-manager-version |  |  |
| secrets.{index}.path |  |  |
| secrets.{index}.env-var-name |  |  |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



### Delete a secret reference within a job definition

Delete a secret reference within a job definition.

**Usage:**

```shell
scw jobs secret delete [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| secret-id | Required | UUID of the secret reference within the job |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



### Get a secret references within a job definition

Get a secret references within a job definition.

**Usage:**

```shell
scw jobs secret get [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| secret-id | Required | UUID of the secret reference within the job |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



### List secrets references within a job definition

List secrets references within a job definition.

**Usage:**

```shell
scw jobs secret list [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| job-definition-id | Required | UUID of the job definition |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



### Update a secret reference within a job definition

Update a secret reference within a job definition.

**Usage:**

```shell
scw jobs secret update [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| secret-id | Required | UUID of the secret reference within the job |
| secret-manager-version |  | Version of the secret in Secret Manager |
| path |  | Path of the secret to mount inside the job (either `path` or `env_var_name` must be set) |
| env-var-name |  | Environment variable name used to expose the secret inside the job (either `path` or `env_var_name` must be set) |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



## 




### Create a trigger

Create a trigger.

**Usage:**

```shell
scw jobs trigger create [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| job-definition-id | Required | UUID of the job definition |
| name | Required | Name of the trigger |
| cron-config.schedule |  | CRON schedule in UNIX format |
| cron-config.timezone |  | Time zone for the CRON schedule |
| cron-config.startup-command.{index} |  | Startup command that will be used by the triggered job |
| cron-config.args.{index} |  | Arguments passed to the startup command used by the triggered job |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



### Delete a trigger

Delete a trigger.

**Usage:**

```shell
scw jobs trigger delete [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| trigger-id | Required | UUID of the trigger |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



### Get a trigger

Get a trigger.

**Usage:**

```shell
scw jobs trigger get [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| trigger-id | Required | UUID of the trigger |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |



### List triggers of a job definition

List triggers of a job definition.

**Usage:**

```shell
scw jobs trigger list [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| job-definition-id | Required | UUID of the job definition |
| order-by | One of: `created_at_asc`, `created_at_desc` | Sorting order of triggers |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw`, `all` | Region to target. If none is passed will use default region from the config |



### Update a trigger

Update a trigger.

**Usage:**

```shell
scw jobs trigger update [arg=value ...]
```


**Args:**

| Name |   | Description |
|------|---|-------------|
| trigger-id | Required | UUID of the trigger |
| name |  | Name of the trigger |
| cron-config.schedule |  | CRON schedule in UNIX format |
| cron-config.timezone |  | Time zone for the CRON schedule |
| cron-config.startup-command.{index} |  | Startup command that will be used by the triggered job |
| cron-config.args.{index} |  | Arguments passed to the startup command used by the triggered job |
| region | Default: `fr-par`<br />One of: `fr-par`, `nl-ams`, `pl-waw` | Region to target. If none is passed will use default region from the config |