Apothic Client CLI and Operations

Deploy apps, run jobs, watch execution, operate sandboxes, manage schedules, and work with shared state from the terminal.

Last updated: 4/23/2026
API Version: v0.1.0
apothic-clientclioperationsreference

Apothic Client CLI and Operations#

The apothic CLI is useful for both development and day-two operations. You can deploy apps, invoke jobs, watch execution, inspect schedules, operate sandboxes, and manage queues or dictionaries without writing ad hoc scripts.

Before you run billable workloads from the CLI, make sure your Apothic account balance is funded through /dashboard/billing.

Core commands#

If you use @apothic.liv(...) or liv=apothic.LivConfig(...), there is no separate deploy command. apothic deploy materializes the generated implementation before packaging the app.

Deploy an app#

apothic deploy app.py
apothic deploy app.py --app-name demo-app

This packages the app in app.py, registers a deployment, and prints the deployment id.

Run a function#

apothic run infer \
  --app-name demo-app \
  --payload '{"args":["hello"],"kwargs":{}}'

Add --watch to stream typed execution events:

apothic run infer \
  --app-name demo-app \
  --payload '{"args":["hello"],"kwargs":{}}' \
  --watch

Run a local entrypoint#

apothic local app.py
apothic local app.py --entrypoint bootstrap --args-json '["world"]'

Use this for local setup logic, smoke scripts, or developer workflows that should not deploy anything.

apothic local ... also works with async local entrypoints. The current App.run_local() path resolves awaitables before printing the result.

Apps and deployments#

List apps:

apothic app list

Inspect a deployed app:

apothic app inspect demo-app

Watch app-level events:

apothic app watch demo-app --snapshot

Clean up stale deployments and keep the latest one:

apothic app cleanup demo-app --keep-latest 1

List and inspect deployments:

apothic deployment list
apothic deployment list --app-name demo-app
apothic deployment inspect deployments:123

Watch a deployment:

apothic deployment watch deployments:123 --snapshot

Tail service startup logs for deployment services that expose startup_log_tail from their health endpoint:

apothic deployment logs deployments:123
apothic deployment logs deployments:123 --function-name serve
apothic deployment logs deployments:123 --health-path /healthz

Stop or delete a deployment:

apothic deployment stop deployments:123
apothic deployment delete deployments:123

Jobs#

List jobs:

apothic job list --app-name demo-app --function-name infer --status running

Inspect a job:

apothic job inspect jobs:123

Read logs:

apothic logs jobs:123

Watch a job:

apothic job watch jobs:123 --snapshot

Cancel a job:

apothic job cancel jobs:123

Resume a buffered job stream directly:

apothic stream jobs:123
apothic stream jobs:123 --last-index 42
apothic stream --checkpoint-json '{"job_id":"jobs:123","last_index":42}'

Schedules#

List scheduled functions for an app:

apothic schedule list demo-app

Inspect one schedule:

apothic schedule inspect demo-app tick

Pause, resume, or trigger immediately:

apothic schedule pause demo-app tick
apothic schedule resume demo-app tick
apothic schedule trigger demo-app tick

Sandboxes#

List the declared sandbox resources on an app:

apothic sandbox list demo-app

Inspect the sandbox definition or one named session:

apothic sandbox inspect demo-app shell
apothic sandbox inspect demo-app shell --sandbox-id demo-session --cwd /workspace

Execute commands:

apothic sandbox exec demo-app shell python -c 'print("hello")' --sandbox-id demo-session
apothic sandbox exec demo-app shell 'echo hello from shell' --sandbox-id demo-session --shell
apothic sandbox exec demo-app shell python -c 'print("stream")' --sandbox-id demo-session --stream

Read, write, and close:

apothic sandbox write demo-app shell /workspace/notes.txt "hello" --sandbox-id demo-session --make-parents
apothic sandbox read demo-app shell /workspace/notes.txt --sandbox-id demo-session
apothic sandbox close demo-app shell --sandbox-id demo-session

Queues#

Create and inspect a queue:

apothic queue create image-jobs
apothic queue length image-jobs

Put and get items:

apothic queue put image-jobs '{"image_id":"img-1"}'
apothic queue get image-jobs --timeout-s 5 --poll-interval-s 0.5

Claim leased work:

apothic queue claim image-jobs --claimer worker-a --timeout-s 30
apothic queue ack image-jobs claim-id-1
apothic queue release image-jobs claim-id-1
apothic queue renew image-jobs claim-id-1 --lease-s 120

Watch queue events:

apothic queue watch image-jobs --snapshot

Dictionaries#

Create and mutate a dictionary:

apothic dict create shared-state
apothic dict set shared-state '"alpha"' '{"score":1}'
apothic dict get shared-state '"alpha"'
apothic dict items shared-state

Acquire a key lease and do compare-and-set:

apothic dict lease-acquire shared-state '"alpha"' --holder worker-a --lease-s 60
apothic dict cas shared-state '"alpha"' '{"score":1}' '{"score":2}'

Watch dictionary events:

apothic dict watch shared-state --snapshot

What the CLI does not cover yet#

The current public CLI does not yet have first-class secret or volume command groups.

Today those are SDK-first:

  • Secret.create(...), Secret.set(...), Secret.list(...), Secret.delete(...)
  • Volume.create(...), Volume.list(...), Volume.delete(...), Volume.ephemeral(...)

Global URL behavior#

By default, the CLI targets https://run.apothic.ai.

Override it with either:

export APOTHIC_BASE_URL=https://run.apothic.ai

or:

apothic deploy app.py --base-url https://run.apothic.ai

Suggested operator workflow#

For a typical deploy-and-verify cycle:

  1. apothic deploy app.py
  2. apothic app inspect my-app
  3. apothic run infer --app-name my-app --payload ... --watch
  4. apothic logs <job_id>
  5. apothic deployment logs <deployment_id> when a service exposes startup_log_tail through its health endpoint
  6. apothic app cleanup my-app --keep-latest 1

What to learn next#