Skip to content
Onebox

CLI commands

Generated from the binary, so it cannot describe a flag the CLI does not have. ob <command> --help is the same text.

Which command changes nothing

Section titled “Which command changes nothing”

Many commands change nothing — status, logs, audit, schema, version and canonical all just report. These five are the ones that get confused with each other, because each one answers “would this deploy work?” from a different place.

CommandReadsContacts the server
ob validatethe project fileno
ob previewthe runtime it would generateno
ob doctorthis runner, its local SSH agent, and the environment’s policyno
ob preflightthe server’s readiness to accept a deployyes
ob planthe project, the server, and writes a plan artifactyes

ob plan is the only one of the five that writes a file, and it writes it locally.

ob

Section titled “ob”
onebox (ob) — plan-before-apply production operations for one application on one server.


You describe what the application is in ob.yml (or ob.yaml); Onebox generates
the Compose runtime, the names, the routing and the supporting services.
Agentless over SSH, health-gated, journaled and fenced.


Usage:
  ob [flags]
  ob [command]


Available Commands:
  abort       revert an interrupted deploy to the previous release (migration-gated)
  approve     record a local human confirmation for one exact executable plan
  audit       who deployed what, when, from which SHA — incl. failed runs
  backup      protect a data service and inspect what can be recovered
  bootstrap   first contact: host setup, registry login, and supporting/data services
  canonical   print the canonical form Onebox understood, with where each value came from
  completion  Generate the autocompletion script for the specified shell
  deploy      show the plan, confirm, and release with health-gated zero downtime
  destroy     tear the app down (typed confirmation; volumes kept unless --volumes)
  doctor      check local runner provenance and deployment safety capabilities
  eject       write the generated runtime into the repository and hand it over for good
  exec        run a command inside a workload or service container
  execution   inspect and recover durable job executions
  help        Help about any command
  init        scaffold ob.yml from the compose file + rollability doctor
  job         plan and run a sealed one-shot operator job
  logs        compose logs from the current release
  plan        refresh → rendered diff + pinned images + command list → plan artifact
  preflight   ask the server whether this project could be deployed (changes nothing)
  preview     render the runtime the declarative contract generates (no target, no changes)
  proxy       manage the host-scoped proxy (proxy.managed: true)
  resume      continue an interrupted deploy from the journal (fences the old runner)
  rollback    re-release the previous release dir (pinned local image)
  schedule    manage host timers for scheduled jobs
  schema      print the JSON Schema for the project file, for editors
  secrets     SOPS-encrypted secrets
  service     manage supporting and data services
  status      recorded versus actual state per workload and service
  validate    validate schema, workloads, and rollability — no side effects
  version     print version and build provenance


Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
  -h, --help            help for ob
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command
      --version         version for ob


Use "ob [command] --help" for more information about a command.

ob abort

Section titled “ob abort”
Revert an interrupted deploy to the release that was serving before it.


Gated on what the interrupted deploy already did: a migration whose effect
cannot be reversed by re-activating a directory refuses, because reverting
the containers would leave them running against data they do not match.


Usage:
  ob abort [flags]


Flags:
      --break-lock             break a stale operation lock after inspecting its holder
      --break-migration-gate   abort past a closed migration gate (you assert schema compatibility)
  -h, --help                   help for abort


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob approve

Section titled “ob approve”
Record a short-lived local confirmation bound to one exact plan and, when supplied, one exact backup report.


Prompts for confirmation, because approving is a human act: a routine plan
asks yes or no, and one that touches data asks for its identity to be typed
back — the release ID for a deploy, the job name for a job run. There is no flag to skip it. The artifact is tamper-evident but
is not an authenticated identity-provider signature. Contacts nothing.


Usage:
  ob approve [flags]


Flags:
      --backup-report string   backup report to bind into this local confirmation
  -h, --help                   help for approve
  -o, --out string             local confirmation artifact path (default "ob-approval.json")
      --plan string            executable plan artifact to approve


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob audit

Section titled “ob audit”
Who did what, when, and from which revision — including runs whose terminal
is long gone.


Reads the append-only journals on the host. One row per invocation, so a
rollback appears as its own event rather than hiding inside the release it
restored.


Usage:
  ob audit [flags]


Flags:
  -n, --count int   journals to show (default 10)
  -h, --help        help for audit


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob backup

Section titled “ob backup”
Backup and recovery for the data services this project declares.


Backup is physical: a base backup plus continuous WAL archiving to the
off-host repository the project's backupTargets name, which is what makes
recovery to a point in time possible rather than recovery to last night.


Declaring a policy does not establish it. `ob backup enable` restarts the
service with archiving on, stages the verified backup tooling, and takes
the first base backup; only then does the service render as protected.


Usage:
  ob backup [flags]
  ob backup [command]


Available Commands:
  create      take a base backup now
  disable     stop archiving; keep every backup already taken
  drill       prove the repository recovers, without touching anything
  enable      establish backup — restarts the service archiving and takes the first backup
  prune       expire backups outside the declared retention
  restore     recover to a point in time and put it in service
  status      what the repository can recover, read from the repository
  verify      prove the archived WAL forms an unbroken chain


Flags:
  -h, --help   help for backup


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command


Use "ob backup [command] --help" for more information about a command.

ob backup create

Section titled “ob backup create”
Take a base backup of a protected service.


Every base backup is complete: the space between them is covered by the WAL
stream rather than by differential backups, so there is no type to choose.


WAL archiving runs continuously and is not this command. Between backups the
recoverable point keeps advancing on its own; a base backup bounds how much
WAL a recovery has to replay, and how far back the window reaches.


Usage:
  ob backup create <service> [flags]


Flags:
      --break-lock   break a stale operation lock after inspecting its holder
  -h, --help         help for create


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob backup disable

Section titled “ob backup disable”
Take a service out of backup.


Archiving stops, the schedules are removed, the service restarts as an
ordinary unprotected one, and its destination credentials are removed from
the host.


The repository is not touched: every backup already taken stays where it
is. Reading or recovering from them needs backup enabled again,
because the binary and credentials that reach the repository live in the
protected service.


What does stop is the recovery window advancing: from here on there is no
new WAL, so the newest recoverable point is the moment this ran.


Usage:
  ob backup disable <service> [flags]


Flags:
      --break-lock       break a stale operation lock after inspecting its holder
      --confirm string   name of the service whose archiving may stop
  -h, --help             help for disable


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob backup drill

Section titled “ob backup drill”
Recover into a throwaway volume, prove the cluster opens and answers, then
discard it. The live service is never touched.


This runs the same code as `ob backup restore` and stops before the last
step, which is the point: a drill that exercised a different path would
prove the drill works rather than that the backups do.


A backup nobody has restored is a hypothesis.


Usage:
  ob backup drill <service> [flags]


Flags:
      --generation string   repository generation to prove (PostgreSQL system identifier or legacy; default: current)
  -h, --help                help for drill
      --to string           RFC 3339 point in time to prove recoverable (default: the newest recoverable point)


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob backup enable

Section titled “ob backup enable”
Make a declared backup policy real.


The order is forced: the credentials are checked, the image is pinned by
registry digest, the generated credential adapter is staged on the host, and only
then does the server restart with archiving on.


The restart is a real restart of the database. It is not complete until the
first base backup exists, because WAL archiving with nothing to replay onto
can recover nothing.


Usage:
  ob backup enable <service> [flags]


Flags:
      --break-lock   break a stale operation lock after inspecting its holder
  -h, --help         help for enable


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob backup prune

Section titled “ob backup prune”
Expire everything the policy no longer promises to keep.


Retention comes from services.<name>.backup.retention.keep,
so this never removes more than the project says it may keep fewer of.


WAL older than the oldest retained backup goes with it: WAL that cannot be
replayed onto any surviving base backup recovers nothing and only costs storage.


Usage:
  ob backup prune <service> [flags]


Flags:
      --break-lock   break a stale operation lock after inspecting its holder
  -h, --help         help for prune


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob backup restore

Section titled “ob backup restore”
Recover a protected service from its repository.


The recovered cluster is always built beside the live one, never over it:
the base backup is fetched into a fresh volume, WAL is replayed to the
requested point, and the result has to start and answer a query before
anything touches the running database. A repository that cannot recover
fails while the database it would have replaced is still serving.


The data being replaced is copied aside first, under a dated volume name,
and retained after restore. Only a later explicit `ob destroy --volumes`
removes it. A restore is run on a day that is already going badly;
it must not be the step that makes it unrecoverable.


Without --to, recovery goes to the newest recoverable point.


The service name has to be typed back with --confirm. Onebox's approval flow
binds a recorded confirmation to an exact plan, and a recovery has no plan to
bind to — so the guard is the name of the thing being replaced, which cannot
be given by accident or by a shell history entry meant for another service.


Usage:
  ob backup restore <service> [flags]


Flags:
      --break-lock          break a stale operation lock after inspecting its holder
      --confirm string      name of the service whose live data may be replaced
      --generation string   repository generation to recover (PostgreSQL system identifier or legacy; default: current)
  -h, --help                help for restore
      --to string           RFC 3339 point in time to recover to (default: the newest recoverable point)


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob backup status

Section titled “ob backup status”
Report what is actually recoverable.


Every figure comes from the repository rather than from the project: the
policy states what should be true, and this states what is. A service whose
policy is declared but never enabled has no repository to ask, and says so.


Usage:
  ob backup status <service> [flags]


Flags:
      --generation string   repository generation to inspect (PostgreSQL system identifier or legacy; default: current)
  -h, --help                help for status


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob backup verify

Section titled “ob backup verify”
Check that the WAL in the repository is continuous.


This is the check worth running on a schedule, and it is not implied by a
backup that exited zero. A base backup with a gapped WAL stream recovers to
the backup and no further — a nightly snapshot wearing the label of
point-in-time recovery — and nothing else notices until someone needs it.


Usage:
  ob backup verify <service> [flags]


Flags:
  -h, --help   help for verify


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob bootstrap

Section titled “ob bootstrap”
Prepare a host that has Docker: create the layout, log in to registries,
start the proxy, and start supporting services.


Onebox never installs Docker implicitly. Install it with operator-managed
provisioning, or declare a remote bootstrap hook that installs a pinned runtime;
the hook runs inside the lock, fence, and journal boundary, and Docker is
verified afterwards.


Run once per host before the first deploy. It is safe to run again — each
step converges rather than repeats. Application images, source and environment
payloads are not required or staged; `ob deploy` binds and releases them.


Usage:
  ob bootstrap [flags]


Flags:
      --break-lock   break a stale bootstrap lock after inspecting its holder
  -h, --help         help for bootstrap


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob canonical

Section titled “ob canonical”
Print the project as Onebox normalised it for an environment: shorthand
expanded, defaults filled, overrides applied.


Values you did not write are marked with their origin, because the difference
between a value someone chose and one that appeared by default is what a
person checking a production configuration needs to see.


Usage:
  ob canonical [flags]


Flags:
  -h, --help           help for canonical
      --origins-only   list every value's origin instead of the document


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob deploy

Section titled “ob deploy”
Release: run pre-release jobs, replace workloads behind their health checks,
verify, and move the current symlink.


This is the only way an application reaches a host. It takes the deploy lock,
fences any older runner, journals every phase, drains connections before
stopping a container, and can roll back. Without --plan it plans inline and
asks for confirmation; with --plan it applies exactly what was reviewed.


If it is interrupted, `ob resume` finishes it and `ob abort` reverts it.


Usage:
  ob deploy [flags]


Flags:
      --approval string                    apply a plan-bound local confirmation artifact
      --backup-report string               apply the backup report bound into the local confirmation
      --break-lock                         break a stale deploy lock after inspecting its holder
  -h, --help                               help for deploy
      --image stringArray                  resolved image as workload=reference, for build-sourced workloads (repeatable)
      --no-rollback                        verify failures halt; never auto-rollback
      --override-migration-backup string   audited break-glass reason for proceeding without a required backup report (requires --approval)
      --plan string                        apply a saved plan artifact (binds config + host state; local confirmation is separate)
      --redeploy                           deploy even when nothing changed (fresh roll of identical content)
  -y, --yes                                skip the confirmation prompt


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob destroy

Section titled “ob destroy”
Tear the application down: every container it owns, its scheduled timers, and
its state directory. An active release is removed with its recorded project
snapshot and interpolation environment, not the current working-tree shape.


Requires the application name typed back. Volumes are kept unless --volumes,
and when they are kept the service credentials are kept with them — a volume
whose credential is gone cannot be opened by a new one. The host proxy survives
unless --proxy is supplied.


Usage:
  ob destroy [flags]


Flags:
  -h, --help      help for destroy
      --proxy     also remove this host's managed proxy
      --volumes   also remove named volumes (DATA LOSS)


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob doctor

Section titled “ob doctor”
Check this runner and the safety capabilities of the environment it targets.


Reports the runner's provenance and whether it satisfies the environment's
minimum version and plan schema, and names every workload and service holding
durable data that nothing is copying off the box, because silence there would
read as approval. A service declaring `backup` is reported as declaring it;
what the repository can actually recover is `ob backup status`. In structured output, automation should gate on
the report status: data.status for pass or warn, and error.details.status for
a failing diagnosis.


Usage:
  ob doctor [flags]


Flags:
  -h, --help   help for doctor


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob eject

Section titled “ob eject”
Write the runtime Onebox generates into your repository as ordinary Compose,
and repoint the affected workloads at it.


This is one way. Onebox will not regenerate or reconcile those services
afterwards. The written file carries none of the identity or routing keys
Onebox adds, so it is a file you own rather than one it half-owns, and your
project file keeps its comments and ordering.


Usage:
  ob eject [flags]


Flags:
  -h, --help                help for eject
      --image stringArray   resolved image as workload=reference (repeatable)
  -o, --out string          repository path to write the runtime to (default: a free name beside the project)
      --overwrite           replace an existing file at the destination


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob exec

Section titled “ob exec”
Run a command inside a running container.


Names a workload or a supporting service. This is an escape hatch: it does not
claim convergence, rollback, idempotence, or output redaction. Onebox journals
the reason, target, target kind, operator, outcome, and command digest — never
the command bytes or passthrough output.


Arguments are passed as a literal vector, so a shell metacharacter is not
interpreted: write `ob exec --reason 'inspect queue' web -- sh -c 'a && b'`
rather than passing the pipeline as one word. Reasons are durable metadata; do
not put credentials or other sensitive values in them.


Usage:
  ob exec <workload|service> -- <command...> [flags]


Flags:
  -h, --help            help for exec
      --reason string   single-line operational justification (max 256 bytes; journaled)


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob execution

Section titled “ob execution”
Inspect durable job checkpoints saved on the managed host. Resume uses the original inputs and successful step outputs, and requires the original release and compatible runtime. Applications remain responsible for idempotency when an interrupted attempt is repeated.


Usage:
  ob execution [flags]
  ob execution [command]


Available Commands:
  abandon     end resumability and release an execution's retention hold
  inspect     show saved inputs, step outcomes, and resume eligibility
  list        list durable executions, newest first
  resume      resume an unsuccessful execution from saved checkpoints


Flags:
  -h, --help   help for execution


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command


Use "ob execution [command] --help" for more information about a command.

ob execution abandon

Section titled “ob execution abandon”
Mark an inactive execution abandoned. It can no longer be resumed and stops protecting its release from cleanup. Saved execution evidence remains available for inspection. Active work must stop before it can be abandoned.


Usage:
  ob execution abandon <id> [flags]


Flags:
      --break-lock   break a stale operation lock after inspecting its holder
  -h, --help         help for abandon


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob execution inspect

Section titled “ob execution inspect”
Read a durable execution by its stable ID, including original inputs, committed outputs, step attempts and systemd invocation IDs. Works independently of the current job declaration. Resume eligibility is provisional: the runner rechecks compatibility and ownership under locks before running.


Usage:
  ob execution inspect <id> [flags]


Flags:
  -h, --help   help for inspect


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob execution list

Section titled “ob execution list”
List the newest durable executions saved on the managed host, including their job, state, original release and provisional resume eligibility. Reads checkpoint files independently of journal retention and the current job declarations.


Usage:
  ob execution list [flags]


Flags:
  -n, --count int   number of newest executions to show (1–1000) (default 20)
  -h, --help        help for list


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob execution resume

Section titled “ob execution resume”
Resume an unsuccessful, unexpired execution with its original inputs and saved outputs. Completed steps are skipped. The host refuses resume while prior work is active or the original release, workflow definition, image, or service runtime is incompatible. An interrupted step may repeat effects; use the stable execution and step IDs for application deduplication.


Usage:
  ob execution resume <id> [flags]


Flags:
      --break-lock   break a stale operation lock after inspecting its holder
  -h, --help         help for resume
      --wait         wait for the resumed activation to finish


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob init

Section titled “ob init”
Scaffold `ob.yml` from the Compose file already in this repository.


A starting point, not permission to deploy: read what it inferred about
roles, persistence, health and job data effects before planning. Writes only
in this repository and contacts nothing.


Usage:
  ob init [flags]


Flags:
  -h, --help   help for init


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob job

Section titled “ob job”
Plan and run one declared `operatorRun: Allowed` job against the current serving release.


Deployment participation is independent: `deploymentPhase` may be None, PreRelease,
or PostRelease. Saved plans bind the release, runtime digest, immutable image,
data effect and inputs so agents can obtain separate approval before execution.


Usage:
  ob job [flags]
  ob job [command]


Available Commands:
  history     execution records of one job, newest first
  logs        journal of one host-supervised job execution
  plan        seal a current-release-bound one-shot job plan
  run         run one operator job from an inline or saved sealed plan


Flags:
  -h, --help   help for job


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command


Use "ob job [command] --help" for more information about a command.

ob job history

Section titled “ob job history”
Read retained execution records for one job across timer and operator triggers. Host-supervised records come from journald; sealed attached runs come from the operation journal. The result is retention-bounded evidence, so an absent success means no retained success was observed, not that the job never succeeded.


Usage:
  ob job history <job> [flags]


Flags:
  -n, --count int   number of newest executions to show (default 20)
  -h, --help        help for history


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob job logs

Section titled “ob job logs”
Stream the exact systemd journal of a host-supervised job execution. By default the newest retained run is selected; --run accepts the run id printed by ob job history. Attached sealed executions retain outcome evidence but do not have a separate host log stream.


Usage:
  ob job logs <job> [flags]


Flags:
  -h, --help         help for logs
      --run string   run id from ob job history; defaults to newest host-supervised run


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob job plan

Section titled “ob job plan”
Observe the current serving release and write a short-lived executable job plan.


The plan binds the exact runtime digest, digest-pinned image, job data effect,
target and expiry. It reads the target and writes only the local plan artifact.


Usage:
  ob job plan <id> [flags]


Flags:
      --backup-report-out string   write a plan-bound backup report template when migration backup is required
  -h, --help                       help for plan
      --input stringArray          input override as NAME=VALUE; repeatable and sealed into the plan
  -o, --out string                 job plan artifact path (default "ob-job-plan.json")


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob job run

Section titled “ob job run”
Run one operator job through the canonical lock, fence, local-confirmation and journal boundary.


A job with schedule configured runs under its installed systemd unit and is
followed by default; Ctrl-C stops following, not the host job. --detach returns
after that unit accepts the run. Unscheduled and migration jobs stay attached.


Humans may pass an id and confirm interactively. Automation should supply a
saved --plan and its separately created local-confirmation artifact through
--approval; migration plans may also require the exact plan-bound --backup-report.


Usage:
  ob job run [id] [flags]


Flags:
      --approval string                    apply a plan-bound local confirmation artifact
      --backup-report string               apply the backup report bound into the local confirmation
      --break-lock                         break a stale operation lock after inspecting its holder
      --detach                             return after the installed host unit accepts the job
  -h, --help                               help for run
      --input stringArray                  input override as NAME=VALUE; repeatable and sealed into the inline plan
      --override-migration-backup string   audited break-glass reason (requires --approval)
      --plan string                        apply a saved job plan artifact


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob logs

Section titled “ob logs”
Stream logs from one workload or Onebox-run supporting service. Reads only.


Log bytes are operator-controlled and may contain secrets; Onebox does not claim
to redact passthrough output.


Usage:
  ob logs <workload|service> [flags]


Flags:
  -f, --follow     stream
  -h, --help       help for logs
      --tail int   lines per service (default 100)


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob plan

Section titled “ob plan”
Read the target's current state, render the runtime, pin every image to a
digest, and write a plan artifact.


Reads the target but changes nothing there. The plan binds the configuration,
the rendered runtime, the host state and the pinned images, and expires after
15 minutes — so a tag that moves afterwards cannot change what is deployed.
Approve it with `ob approve --plan`, apply it with `ob deploy --plan`.


Usage:
  ob plan [flags]


Flags:
      --backup-report-out string   write a plan-bound backup report template when migration backup is required
  -h, --help                       help for plan
      --image stringArray          resolved image as workload=reference, for build-sourced workloads (repeatable)
  -o, --out string                 plan artifact path (default "ob-plan.json")


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob preflight

Section titled “ob preflight”
Render the project locally, then ask the server what would stand in the way:
a missing container runtime, a missing Docker Compose plugin, a missing or
incompatible Docker Buildx image resolver, a base path this account cannot
write, a derived name already held by something Onebox does not own, or a
missing ingress network.


The host prerequisites are the same set `ob bootstrap` and every deploy
assert, so a host this command accepts is one they accept too.


Every problem is reported at once rather than the first one, and nothing is
created, renamed or removed.


Usage:
  ob preflight [flags]


Flags:
  -h, --help   help for preflight


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob preview

Section titled “ob preview”
Load a onebox.run/v1alpha1 Application, resolve the environment's overrides, and print
the Compose runtime Onebox would generate, with its content digest.


Nothing is contacted and nothing is written. Environment values are redacted:
a preview must never put a secret on a terminal.


Usage:
  ob preview [flags]


Flags:
      --digest-only         print the content digest and nothing else
  -h, --help                help for preview
      --image stringArray   resolved image for a build-sourced workload, as workload=reference (repeatable)
      --raw                 do not redact environment values
      --release string      release identity to stamp (default "preview")


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob proxy

Section titled “ob proxy”
Manage the host-scoped proxy owned by this host's sole Onebox application.


The proxy outlives application releases and holds the public ports and
certificates. A different application identity is refused before mutation.


Usage:
  ob proxy [flags]
  ob proxy [command]


Available Commands:
  apply       converge the host proxy — diff shown; unchanged config never touches the container (ACME-safe)


Flags:
  -h, --help   help for proxy


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command


Use "ob proxy [command] --help" for more information about a command.

ob proxy apply

Section titled “ob proxy apply”
Reconfigure the host proxy from the sole owning application's routes.


Taken under the host lock because the proxy belongs to the box rather than to
a release. Cross-application route merging is not supported.


Usage:
  ob proxy apply [flags]


Flags:
      --break-lock   break a stale host lock after inspecting its holder
  -h, --help         help for apply


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob resume

Section titled “ob resume”
Continue a deploy that was interrupted, from the journal.


Fences the runner that stopped so it cannot wake up and act on stale state,
then carries on from the last completed phase. Use when the interruption was
the runner's — a lost connection, a killed process — rather than the
release's.


Usage:
  ob resume [flags]


Flags:
  -h, --help   help for resume


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob rollback

Section titled “ob rollback”
Re-activate the previous release from the directory still on the host.


Nothing is pulled and nothing is rebuilt: the previous release's images are
already there, which is what makes this fast and available when a registry is
not. Refused when there is no previous release, or when its snapshot is
unavailable or unusable. Supporting services are not rolled back, so a
migration a job already applied stays applied — moving the symlink does
not undo it.


Usage:
  ob rollback [flags]


Flags:
  -h, --help   help for rollback


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob schedule

Section titled “ob schedule”
Manage the systemd timers generated for scheduled jobs.


Timers outlive the Onebox process and the package installed on the operator
workstation. `apply` explicitly reconciles their units after a runner or
configuration change without deploying a release. `list` reads timer state;
job history and logs live under `ob job`.


Usage:
  ob schedule [flags]
  ob schedule [command]


Available Commands:
  apply       reconcile scheduled-job units without deploying a release
  list        declared scheduled jobs with timer state and next elapse
  pause       stop a scheduled job's timer until it is resumed
  resume      start a paused scheduled job's timer again


Flags:
  -h, --help   help for schedule


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command


Use "ob schedule [command] --help" for more information about a command.

ob schedule apply

Section titled “ob schedule apply”
Converge every declared scheduled-job timer, service, runner, and failure notifier to what the current Onebox runner generates.


Taken under the application lock and fence so a deploy or host-fired job cannot modify the same runtime concurrently. This is the explicit post-upgrade path; upgrading the local package never mutates a remote host by itself.


Usage:
  ob schedule apply [flags]


Flags:
      --break-lock   break a stale operation lock after inspecting its holder
  -h, --help         help for apply


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob schedule list

Section titled “ob schedule list”
List every job that declares a schedule beside what the host's timer says: whether it is active, when it fires next, and when it last fired. A job an operator stopped with `ob schedule pause` shows its timer as paused; who paused it and why are in `ob status` and in the JSON output. Reads only.


Usage:
  ob schedule list [flags]


Flags:
  -h, --help   help for list


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob schedule pause

Section titled “ob schedule pause”
Stop one job's timer. The units stay installed and a deploy keeps updating them, so a fix still lands; only the firing stops, and it stays stopped until `ob schedule resume`.


A run already under way is left alone. `--reason` is required and is kept on the host with the operator and the time, because a job that is deliberately not running looks exactly like one that is broken. `ob status` reports a paused job on its own line for the same reason.


Usage:
  ob schedule pause <job> [flags]


Flags:
      --break-lock      break a stale operation lock after inspecting its holder
  -h, --help            help for pause
      --reason string   why this job is being stopped; kept on the host and shown by ob status


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob schedule resume

Section titled “ob schedule resume”
Start a paused job's timer and clear the record of the pause.


The next run is the next scheduled elapse: resuming does not run the job now, and does not make up the firings missed while it was paused. Use `ob job run` for an immediate run.


Usage:
  ob schedule resume <job> [flags]


Flags:
      --break-lock   break a stale operation lock after inspecting its holder
  -h, --help         help for resume


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob schema

Section titled “ob schema”
Write the JSON Schema for the `onebox.run/v1alpha1` Application resource.


Reference it from the first line of a project so an editor can offer
completion, hover documentation and inline errors:


  # yaml-language-server: $schema=https://onebox.run/schemas/application/v1alpha1/application.schema.json


Or keep a copy in the repository with --out, which is what an editor
needs when the machine is offline.


Usage:
  ob schema [flags]


Flags:
  -h, --help         help for schema
  -o, --out string   write to this path instead of standard output


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob secrets

Section titled “ob secrets”
SOPS-encrypted secrets for this project.


`list` names every value-free declaration and its stable entry ID. `edit`
decrypts the selected source to a temporary file, opens an editor, and re-encrypts.
`push` renders the decrypted values into the current release on the host
and restarts what reads them. Plaintext never enters the project file, the
generated runtime, or any plan.


Usage:
  ob secrets [flags]
  ob secrets [command]


Available Commands:
  edit        open one encrypted source in $EDITOR via sops
  list        list value-free secret declarations and stable entry IDs
  push        re-render secrets into the live release and restart workloads if changed


Flags:
  -h, --help   help for secrets


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command


Use "ob secrets [command] --help" for more information about a command.

ob secrets edit

Section titled “ob secrets edit”
Decrypt the secrets file, open it in $EDITOR, and re-encrypt on save.


Plaintext exists only in a temporary file for the life of the editor. It
never enters the project file, the generated runtime, or any plan.


Usage:
  ob secrets edit [entry-id] [flags]


Flags:
  -h, --help   help for edit


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob secrets list

Section titled “ob secrets list”
List the encrypted secret declarations active in the selected environment.


The result contains stable entry IDs, source paths, scopes, output paths, and
affected workloads, but never decrypted values. Pass an ID to `ob secrets edit`
when more than one editable source exists.


Usage:
  ob secrets list [flags]


Flags:
  -h, --help   help for list


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob secrets push

Section titled “ob secrets push”
Render the complete decrypted secret graph into the current release on the host and
replace every workload that reads the declared secret graph when any value changes.


The payload is uploaded and compared on the host even for a no-op; unchanged values do
not replace or restart workloads. Refused when secret declarations differ from the
deployed release, or when that release predates opaque secret generations. In either
case, deploy first.


Usage:
  ob secrets push [flags]


Flags:
  -h, --help   help for push


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob service

Section titled “ob service”
Manage the supporting services this project declares.


They run in their own Compose projects, so no deploy and no rollback can
stop them or remove their volumes. `apply` converges them to what the
project declares; a major version change a driver cannot perform in place
is refused rather than attempted.


Usage:
  ob service [flags]
  ob service [command]


Available Commands:
  apply       planned service convergence — diff shown, destructive mounts refused without --allow-destructive-mounts


Flags:
  -h, --help   help for service


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command


Use "ob service [command] --help" for more information about a command.

ob service apply

Section titled “ob service apply”
Converge the supporting services to what the project declares.


Each runs in its own Compose project, so this never touches a release and a
release never touches it. A change a driver can apply in place is applied; a
major version change it cannot — a data directory the new version could not
open — is refused with what to do instead, rather than replacing the
container and leaving the data intact and unreachable.


Usage:
  ob service apply [flags]


Flags:
      --allow-destructive-mounts   permit only the mount detachments named in the service plan
      --break-lock                 break a stale operation lock after inspecting its holder
  -h, --help                       help for apply


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob status

Section titled “ob status”
Compare what the host records against what it is actually running, per
workload and service.


Reads only. Reports the recorded release, each container's release label and
health, replica shortfalls, the proxy, and any incomplete deploy. Exits
non-zero on divergence so a script can branch on it.


Usage:
  ob status [flags]


Flags:
  -h, --help   help for status


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob validate

Section titled “ob validate”
Load the project, expand shorthand, apply defaults and the environment's
overrides, and check every rule the contract states.


Contacts nothing and writes nothing. Build metadata is valid before CI supplies
a release image; plan and deploy require that image via `--image`. A failure
names the field, the line and the constraint; `ob canonical` shows what was
understood.


Usage:
  ob validate [flags]


Flags:
  -h, --help   help for validate


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command

ob version

Section titled “ob version”
Print the version and build provenance of this binary.


Environment policy can require a released runner, so a commit-derived or
dirty build is reported as such rather than as a version.


Usage:
  ob version [flags]


Flags:
  -h, --help   help for version


Global Flags:
  -c, --config string   path to the project YAML file (default "ob.yml")
  -e, --env string      environment name (default "production")
      --output string   output mode for supported commands: human|json|ndjson (see the CLI reference) (default "human")
  -v, --verbose         print every remote command