---
title: blossom job:run:create
url: "/docs/reference/cli/job/run/create/"
canonical_url: https://docs.blossom88.com/docs/reference/cli/job/run/create/
markdown_url: https://docs.blossom88.com/docs/reference/cli/job/run/create.md
summary: Run a saved Job or an ad hoc Environment command
categories:
- cli
- reference
---

# blossom job:run:create

Run a saved Job or an ad hoc Environment command

## Usage

    blossom job:run:create [--job JOB] [--environment ENVIRONMENT] [--command COMMAND] [--data DATA] [--follow] [--timestamps]

## Flags

| Flag | Description |
| --- | --- |
| `--job` | Saved Job id; alternative to --environment |
| `--environment` | Environment id for an ad hoc command; alternative to --job |
| `--command` | Ad hoc command using default resources; alternative to --data |
| `--data, -d` | Job Run YAML/JSON, file, or URL; supports custom-image source; alternative to --command |
| `--follow, -f` | Follow this execution to its terminal result |
| `--timestamps` | Show log timestamps. Default: true. |

Create a Job Run using its Environment Release or a custom image. Choose exactly one target: a saved Job or an Environment for an
ad hoc command. Neither path creates a Build or Deploy.

    blossom job:run:create --job job-100 --follow
    blossom job:run:create --environment environment-100 --command "bin/rails reports:generate" --follow
    blossom job:run:create --environment environment-100 --data job_run.yml --follow

With `--job`, use the saved definition without command or data overrides.
With `--environment`, use exactly one of `--command` for a command with defaults
or `--data` for structured execution settings. No saved Job is created. Keep
the Environment identity in `--environment`, outside the data file.

job_run.yml:

```yaml
job_run:
  command: printf hello
  size: inherit
  timeout_seconds: 120
```

For a custom image, add this source to `job_run` (also supported in saved Jobs):

```yaml
  source:
    type: external_image
    image: docker.io/library/python:3.13
    environment_variables: [S3_BUCKET]
    # registry_id: container_registry-100
```

Use a full image tag or digest, matching the Location's architecture. Tags
resolve once when a Run is accepted; its resolved digest stays fixed. No successful
Release is required. Commands run through `/bin/sh`; the image entrypoint is
replaced. Custom images receive only the listed Environment variables (none by
default), with the same private network access. Private images require a
configured username/token Container Registry in the same Account matching the image host.
Blossom-managed images use the Environment Release source instead.

Data files expand local environment variables; write `$$VAR` to pass a literal
`$VAR` for expansion inside the application runtime.

By default, a Run matches your Environment's largest Service requirements: the highest
per-container CPU and memory among enabled Services, without multiplying replicas.
The maxima may come from different Services. With no enabled Services, Blossom
uses 0.5 vCPU / 875 MB. Each Run snapshots its size when accepted. The default
execution timeout is 900 seconds.
Optional `size` values are `inherit`, `default` or `small` (0.5 vCPU / 875 MB),
`medium` (1 vCPU / 1.75 GB), `large` (2 vCPU / 3.5 GB), and
`x-large` (4 vCPU / 7.8 GB).
For a specialized allocation, supply `resources.cpu` and `resources.memory_mb`
instead of `size`; the two shapes cannot be combined.
Blossom uses existing headroom or prepares Capacity within your Location capacity ceiling.
Preparation can wait up to 15 minutes and can be canceled before the command
starts. The execution timeout begins separately. Manage reserved capacity and request a higher ceiling on Locations. Release
overrides and schedules are not supported
by this command.

With `--follow`, failed, timed-out, or canceled Runs return a nonzero CLI exit
status. Without it, acceptance is not proof of successful execution.

    blossom job:run:show --id job_run-100
    blossom job:run:logs --id job_run-100 --follow
    blossom job:run:cancel --id job_run-100

Launching a saved Job requires `job:write`; an ad hoc command requires
`environment:write`. Reading output requires `job:read`, and
canceling requires `job:write`. Job write access alone does not grant permission
to execute an arbitrary Environment command.

Commands may change application data. Cancellation does not undo changes the
command has already made.