# Run CLI reference

Source: `@socra/run-cli@0.4.1`.

This reference includes every command, argument, and option declared by this released package. Defaults and accepted values are included where the package declares them. Command-specific validation and permissions also apply; see the [API reference](/docs/run/reference/api) for resource contracts.

Use `socra run --help`, or append `--help` to any command, to inspect the locally installed version.

## socra run

Build and run code on Socra

| Command | Purpose |
| --- | --- |
| `socra run deploy` | Build and deploy a workload |
| `socra run rollback` | Redeploy an immutable revision |
| `socra run logs` | Print or follow deployment logs |
| `socra run events` | Show deployment lifecycle events |
| `socra run status` | Show deployment health and URL |
| `socra run workload` | Stable runnable services and jobs |
| `socra run deployment` | Deployment executions |
| `socra run revision` | Immutable successful runtime revisions |
| `socra run route` | Custom hostnames routed to service workloads |

## socra run deploy

Build and deploy a workload

```text
socra run deploy <workload> [options]
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `workload` | Yes | Workload name |

### Options

| Option | Input | Description |
| --- | --- | --- |
| `--project` | Value | Socra project id or slug (or SOCRA_PROJECT) |
| `--image` | Value | OCI image pinned by sha256 digest |

## socra run rollback

Redeploy an immutable revision

```text
socra run rollback <revision>
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `revision` | Yes | Revision id |

## socra run logs

Print or follow deployment logs

```text
socra run logs <deployment> [options]
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `deployment` | Yes | Deployment id |

### Options

| Option | Input | Description |
| --- | --- | --- |
| `--follow` | Presence flag | Stream until deployment completes |

## socra run events

Show deployment lifecycle events

```text
socra run events <deployment>
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `deployment` | Yes | Deployment id |

## socra run status

Show deployment health and URL

```text
socra run status <deployment>
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `deployment` | Yes | Deployment id |

## socra run workload

Stable runnable services and jobs

| Command | Purpose |
| --- | --- |
| `socra run workload create` | Create a workload |
| `socra run workload get` | Show a workload |
| `socra run workload list` | List workloads |
| `socra run workload update` | Update workload runtime settings |
| `socra run workload delete` | Delete an unused workload |

## socra run workload create

Create a workload

```text
socra run workload create <name> [options]
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `name` | Yes | Workload name |

### Options

| Option | Input | Description |
| --- | --- | --- |
| `--project` | Value | Socra project id or slug (or SOCRA_PROJECT) |
| `--kind` | Value | service or job |
| `--port` | Value | Listening port |

## socra run workload get

Show a workload

```text
socra run workload get <id>
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Workload id |

## socra run workload list

List workloads

```text
socra run workload list [options]
```

### Options

| Option | Input | Description |
| --- | --- | --- |
| `--project` | Value | Socra project id or slug (or SOCRA_PROJECT) |
| `--limit` | Value | Page size |
| `--after` | Value | Page cursor |

## socra run workload update

Update workload runtime settings

```text
socra run workload update <id> [options]
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Workload id |

### Options

| Option | Input | Description |
| --- | --- | --- |
| `--kind` | Value | service or job |
| `--port` | Value | Listening port |
| `--variables` | Value | JSON object of plain variables |
| `--secrets` | Value | JSON object mapping env names to sec_ or sev_ ids |
| `--release-command` | Value | JSON argv array |

## socra run workload delete

Delete an unused workload

```text
socra run workload delete <id>
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Workload id |

## socra run deployment

Deployment executions

| Command | Purpose |
| --- | --- |
| `socra run deployment create` | Create and wait for a deployment |
| `socra run deployment get` | Show a deployment |
| `socra run deployment list` | List deployments |
| `socra run deployment logs` | Print or follow deployment logs |
| `socra run deployment events` | Show deployment lifecycle events |
| `socra run deployment health` | Show deployment health and URL |
| `socra run deployment cancel` | Cancel a deployment |

## socra run deployment create

Create and wait for a deployment

```text
socra run deployment create <workload> [options]
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `workload` | Yes | Workload name |

### Options

| Option | Input | Description |
| --- | --- | --- |
| `--project` | Value | Socra project id or slug (or SOCRA_PROJECT) |
| `--image` | Value | OCI image pinned by sha256 digest |

## socra run deployment get

Show a deployment

```text
socra run deployment get <id>
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Deployment id |

## socra run deployment list

List deployments

```text
socra run deployment list [options]
```

### Options

| Option | Input | Description |
| --- | --- | --- |
| `--project` | Value | Socra project id or slug (or SOCRA_PROJECT) |
| `--status` | Value | Deployment status |
| `--limit` | Value | Page size |
| `--after` | Value | Page cursor |

## socra run deployment logs

Print or follow deployment logs

```text
socra run deployment logs <id> [options]
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Deployment id |

### Options

| Option | Input | Description |
| --- | --- | --- |
| `--follow` | Presence flag | Stream until deployment completes |

## socra run deployment events

Show deployment lifecycle events

```text
socra run deployment events <id>
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Deployment id |

## socra run deployment health

Show deployment health and URL

```text
socra run deployment health <id>
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Deployment id |

## socra run deployment cancel

Cancel a deployment

```text
socra run deployment cancel <id>
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Deployment id |

## socra run revision

Immutable successful runtime revisions

| Command | Purpose |
| --- | --- |
| `socra run revision get` | Show a revision |
| `socra run revision list` | List revisions |
| `socra run revision rollback` | Redeploy the exact revision configuration |

## socra run revision get

Show a revision

```text
socra run revision get <id>
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Revision id |

## socra run revision list

List revisions

```text
socra run revision list [options]
```

### Options

| Option | Input | Description |
| --- | --- | --- |
| `--project` | Value | Socra project id or slug (or SOCRA_PROJECT) |
| `--limit` | Value | Page size |
| `--after` | Value | Page cursor |

## socra run revision rollback

Redeploy the exact revision configuration

```text
socra run revision rollback <id>
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Revision id |

## socra run route

Custom hostnames routed to service workloads

| Command | Purpose |
| --- | --- |
| `socra run route create` | Route a claimed Hostname to a workload |
| `socra run route get` | Show a route |
| `socra run route list` | List routes |
| `socra run route update` | Retarget or enable/disable a route |
| `socra run route delete` | Delete a route |

## socra run route create

Route a claimed Hostname to a workload

```text
socra run route create <hostname> [options]
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `hostname` | Yes | Fully-qualified hostname |

### Options

| Option | Input | Description |
| --- | --- | --- |
| `--project` | Value | Socra project id or slug (or SOCRA_PROJECT) |
| `--workload` | Value | Workload name |

## socra run route get

Show a route

```text
socra run route get <id>
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Route id |

## socra run route list

List routes

```text
socra run route list [options]
```

### Options

| Option | Input | Description |
| --- | --- | --- |
| `--project` | Value | Socra project id or slug (or SOCRA_PROJECT) |
| `--hostname` | Value | Hostname filter |
| `--workload` | Value | Workload filter |
| `--status` | Value | active or disabled |
| `--limit` | Value | Page size |
| `--after` | Value | Page cursor |

## socra run route update

Retarget or enable/disable a route

```text
socra run route update <id> [options]
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Route id |

### Options

| Option | Input | Description |
| --- | --- | --- |
| `--workload` | Value | Workload name |
| `--status` | Value | active or disabled |

## socra run route delete

Delete a route

```text
socra run route delete <id>
```

### Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `id` | Yes | Route id |

## Next step

Return to the [Run overview](/docs/run).

---

Company: Socra — Multiply Your Judgment
Canonical URL: https://cloud.socra.com/docs/run/reference/cli