Documentation v0.42.0 Command Line Interface

Command Line Interface

Global Options

Obelisk Server

Running the Server

obelisk server run [OPTIONS]

Options:

If --deployment is not provided, Obelisk uses the Enqueued or Active deployment from the database.

The server requires an app name, from app_name in app.toml or from OBELISK_APP_NAME. The name selects the default SQLite directory, ${DATA_DIR}/apps/${APP_NAME}/sqlite. See Configuration.

Verifying the Server Configuration

Instead of running the server one might wish just to verify the TOML configuration. This includes:

obelisk server verify [OPTIONS]

Options:

The availability flag allows a developer to verify a deployment before an app or platform admin has supplied required values or approved public environment names, secrets, outbound HTTP destinations, or exec activities. These gaps produce warnings. Invalid manifests, missing files, compile errors, and link errors still fail. Activation always checks the actual configuration strictly.

Obelisk Deployment

Manage deployments (component configurations) stored in the database.

Verifying a local deployment

Compile and verify a deployment without starting a server or accessing its database:

obelisk deployment verify --server-config server.toml --app-config app.toml --deployment deployment.toml

Options:

Submitting a deployment

Upload a deployment TOML as a new deployment; print the new deployment ID.

obelisk deployment submit [OPTIONS] [PATH]

Arguments:

Options:

Enqueueing a deployment

Submit a deployment (if a file is given) and enqueue it for activation on the next server restart.

obelisk deployment enqueue [OPTIONS] [PATH|ID]

Arguments:

Options:

Applying a deployment

Submit a deployment (if a file is given) and hot-redeploy immediately. Fails if hot-redeploy is not possible.

obelisk deployment apply [OPTIONS] [PATH|ID]

Arguments:

Options:

Listing deployments

obelisk deployment list [OPTIONS]

Options:

Showing the active deployment ID

obelisk deployment active [OPTIONS]

Options:

Showing a deployment

Show the stored deployment.toml for a deployment, a single deployment-owned source file, or the stored TOML manifest rendered as JSON. The TOML output preserves the submitted formatting and comments.

obelisk deployment show [OPTIONS] <ID> [FILE]

Arguments:

Options:

Retrieving a deployment

Retrieve a deployment to disk as a re-submittable deployment.toml plus its deployment-owned source files. By default the exported TOML omits generated content digests and JavaScript module metadata.

obelisk deployment pull [OPTIONS] <ID>

Arguments:

Options:

Obelisk Execution

Submitting an execution

obelisk execution submit [OPTIONS] <function> [parameters]...

Arguments:

Options:

Listing executions

obelisk execution list [OPTIONS]

Options:

Example

obelisk execution list -e E_01KPFKGAGSH91DRVBJZ3AK0T8A --show-derived
E_01KPFKGAGSH91DRVBJZ3AK0T8A.o:3-fibo_1 `Finished: OK` benchmark-fibo:activity/fiboa.fibo `2026-04-18 06:12:31.391616296 UTC`
E_01KPFKGAGSH91DRVBJZ3AK0T8A.o:2-fibo_1 `Finished: OK` benchmark-fibo:activity/fiboa.fibo `2026-04-18 06:12:31.390617507 UTC`
E_01KPFKGAGSH91DRVBJZ3AK0T8A.o:1-fibo_1 `Finished: OK` benchmark-fibo:activity/fiboa.fibo `2026-04-18 06:12:31.388883844 UTC`
E_01KPFKGAGSH91DRVBJZ3AK0T8A `Finished: OK` benchmark-fibo:workflow/fibow.fiboa `2026-04-18 06:12:31.386857278 UTC`

Getting the current execution state

obelisk execution status [OPTIONS] <EXECUTION_ID>

Arguments:

Options:

Getting the final result

obelisk execution result [OPTIONS] <EXECUTION_ID>

Arguments:

Options:

Fetching logs

obelisk execution logs [OPTIONS] <EXECUTION_ID>

Arguments:

Options:

Showing execution events

obelisk execution events [OPTIONS] <EXECUTION_ID>

Arguments:

Options:

Example

obelisk execution events E_01KPFKGAGSH91DRVBJZ3AK0T8A
1 `2026-04-18 06:12:31.387608348 UTC` Locked(`2026-04-18 06:12:33.387608348 UTC`, workflow:fibow_rs:sha256:11d530...)
2 `2026-04-18 06:12:31.388883844 UTC` HistoryEvent(JoinSetCreate(o:1-fibo))
3 `2026-04-18 06:12:31.388883844 UTC` HistoryEvent(JoinSetRequest(ChildExecutionRequest(...)))
...
11 `2026-04-18 06:12:31.392790003 UTC` Finished

Showing execution responses

obelisk execution responses [OPTIONS] <EXECUTION_ID>

Arguments:

Options:

Example

obelisk execution responses E_01KPFKGAGSH91DRVBJZ3AK0T8A
1 `2026-04-18 06:12:31.390150065 UTC` o:1-fibo completed successfully: E_01KPFKGAGSH91DRVBJZ3AK0T8A.o:1-fibo_1
2 `2026-04-18 06:12:31.391402695 UTC` o:2-fibo completed successfully: E_01KPFKGAGSH91DRVBJZ3AK0T8A.o:2-fibo_1
3 `2026-04-18 06:12:31.392479831 UTC` o:3-fibo completed successfully: E_01KPFKGAGSH91DRVBJZ3AK0T8A.o:3-fibo_1

Cancelling an activity, cancellable workflow, or delay request

obelisk execution cancel [OPTIONS] <ID>

Arguments:

Options:

Workflow cancellation is accepted only for workflows whose exported function name ends in -cancellable. This lets an operator release a workflow that is stuck on a long-lived stub, blocked on a child, or unable to replay after a failed upgrade. Obelisk does not run the cancelled workflow again; it closes that workflow's join sets and cancels activities, delays, and cancellable workflow children held by those sets. See Cancellation.

Providing the result of a stubbed activity

obelisk execution stub [OPTIONS] <EXECUTION_ID> <RETURN_VAL>

Arguments:

Options:

Pausing an execution or delay

Pause a workflow execution, pending activity execution, or pending delay, preventing it from being picked up until unpaused. A running activity cannot be paused while it is locked; pause applies between activity runs. Cancel a running activity when it must be interrupted immediately.

obelisk execution pause [OPTIONS] <ID>

Arguments:

Options:

Resuming a paused execution or delay

obelisk execution unpause [OPTIONS] <ID>

Arguments:

Options:

Replaying an execution

Replay a workflow execution from its execution log, checking for non-determinism. The response indicates whether the execution is advanceable, finished, blocked, or if replay failed.

obelisk execution replay [OPTIONS] <EXECUTION_ID>

Arguments:

Options:

Persisting workflow backtraces

Replay a workflow and persist its call-site backtraces:

obelisk execution persist-backtraces [OPTIONS] <EXECUTION_ID>

Options:

Advancing a paused execution

Advance a paused workflow execution by replaying it and applying the next captured writes. This enables step-through debugging: create an execution with --paused, then call replay to preview what would happen next, and advance to apply those writes. This lets you inspect each step before it takes effect, trim events, or mark child executions and delays as paused for further control.

obelisk execution advance [OPTIONS] <EXECUTION_ID>

Arguments:

Options:

Upgrading an execution

Upgrade a workflow execution to the current component version in the active deployment. Looks up the execution's FFQN, finds the component exporting it in the active deployment, and upgrades the execution from its current digest to the new one.

obelisk execution upgrade [OPTIONS] <EXECUTION_ID>

Arguments:

Options:

Obelisk Admin

The obelisk admin commands expose operator-only maintenance and persisted system events through the authenticated API:

obelisk admin node-run-id
obelisk admin events list --level warning
obelisk admin events get <event-id>
obelisk admin storage show

Retain execution trees, inactive deployments, or system events by age or count. Use --dry-run before destructive retention operations:

obelisk admin executions retain --max-age 30d --dry-run
obelisk admin deployments retain --count 20 --dry-run
obelisk admin events retain --max-age 30d

Delete explicit execution trees or inactive deployments with admin executions delete and admin deployments delete. Non-terminal execution trees require --force; an execution root that belongs to the active deployment cannot be force-deleted. Deployment retention always keeps active and enqueued deployments. Add --json for machine-readable output.

Obelisk Component

Listing available components and functions

obelisk component list [OPTIONS]

Options:

Pushing a component to an OCI registry

Push a WASM or JS component to an OCI registry with Obelisk deployment metadata embedded in the image manifest. Use docker login to authenticate against the OCI registry first.

obelisk component push --deployment <DEPLOYMENT> <COMPONENT_NAME> <OCI>

Arguments:

Adding a component to the deployment configuration

Add a component to a deployment TOML configuration file from an OCI reference. The component type is auto-detected from the OCI image metadata embedded by component push.

obelisk component add [OPTIONS] --deployment <DEPLOYMENT> <LOCATION> <COMPONENT_NAME>

Arguments:

Options:

Obelisk Generate

Generating extension functions

The extension WIT files of a given component can be generated using:

obelisk generate wit-extensions [OPTIONS] <COMPONENT_TYPE> <INPUT_WIT_DIRECTORY> <OUTPUT_DIRECTORY>

Arguments:

Options:

Generating WIT support functions

As described in Runtime Support, Obelisk provides types and host functions described as WIT interfaces.

obelisk generate wit-support [OPTIONS] <COMPONENT_TYPE> <OUTPUT_DIRECTORY>

Arguments:

Options:

Generating WIT dependencies

Generate WIT dependency folder based on activities and workflows found in the provided deployment TOML:

obelisk generate wit-deps [OPTIONS] --deployment <DEPLOYMENT> <OUTPUT_DIRECTORY>

Arguments:

Options:

Starting a new app

Create a JavaScript starter app:

obelisk generate new [NAME]

With NAME, Obelisk creates a new directory of that name. NAME must be a valid app DNS label. Without NAME, it writes into the current directory and derives a lowercase app slug from that directory's name. The starter contains app.toml, deployment.toml, a webhook, a workflow, and an HTTP activity. Existing files and directories are preserved. See the generated README.md to run it.

Generating server configuration

Print a default server configuration to stdout, or write it to a file when OUTPUT is given:

obelisk generate server-config [OPTIONS] [OUTPUT]

Arguments:

Options:

Generating app configuration

Print a default app configuration to stdout, or write it to a file when OUTPUT is given:

obelisk generate app-config [OPTIONS] [OUTPUT]

Arguments:

Options:

Splitting a 0.41 server configuration

Move app-owned policy ([secrets], [public_env], [[outbound_http.allowed_host]], and [allowed_exec_activities]) from an existing server.toml into app.toml:

obelisk generate split-config [OPTIONS] --server-config <SERVER_CONFIG>

Options:

See Migrating from 0.41 to 0.42.

Generating deployment configuration

Print a default deployment configuration to stdout, or write it to a file when OUTPUT is given:

obelisk generate deployment [OPTIONS] [OUTPUT]

Arguments:

Options:

Generating secret-exposure digests

Calculate the reviewed configuration digests for exec activities and for components that request plaintext secrets through exposed_secrets. The output is pasteable app.toml configuration: [allowed_exec_activities] entries for exec activities and [secrets.<name>.exposed_to] grants.

obelisk generate secret-config-digest [OPTIONS] --deployment <DEPLOYMENT> [COMPONENT_NAME]

Arguments:

Options:

Generating a deployment ID

Generate a new deployment ID:

obelisk generate deployment-id

Options:

Generating an execution ID

Generate a new execution ID:

obelisk generate execution-id

Options:

Generating an API token

Generate a random API token. Stdout contains only the token so the command can be used directly in environment injection. In an interactive terminal, the corresponding api.token_hashes entry is also printed to stderr. The plaintext token is printed once and never stored; revoke it by deleting its hash line and restarting the server. See Authentication.

obelisk generate token

Options:

Generating a coding-agent prompt

Print a prompt context for authoring an Obelisk application with a coding agent:

obelisk generate prompt <DESCRIPTION>

Arguments:

Example

obelisk generate prompt 'Create a daily task that monitors GitHub org "my-org"' | claude