Skip to main content

ORCHER CLI

Run ORCHER on your machine, and start, watch and control workflows on any engine, from your terminal.


CI Apache 2.0

orcher works the same against a local engine, a self-hosted one, or ORCHER Cloud.

  • Local engine: orcher dev start runs the engine and its database in Docker, ready in seconds
  • Run: start a workflow with JSON input or key=value parameters, and wait for its result
  • Inspect: list, filter and search executions; see each one's status, result, journal, tasks and log
  • Control: cancel or terminate a workflow, send it an event, or act on many at once
  • Cloud: log in to ORCHER Cloud and keep a context per environment
  • Scriptable: -o json, -o yaml or -o name, and exit codes that mean something

Install

macOS and Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/orcher-io/cli/releases/latest/download/orcher-installer.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://github.com/orcher-io/cli/releases/latest/download/orcher-installer.ps1 | iex"

Or with a package manager:

Homebrew brew install orcher-io/tap/orcher
Cargo cargo install orcher
pip pip install orcher, or run it without installing: uvx orcher
npm npm install -g orcher, or run it without installing: npx orcher

Every release has binaries for macOS (Apple silicon and Intel), Linux (x86_64 and arm64, glibc and musl) and Windows (x86_64) on its release page, with checksums.


Quick start

Start a local engine. It needs Docker, and keeps its data until you delete it:

orcher dev start                           # the engine on localhost:50051

Run a worker against it (the quickstart has one in Python, TypeScript and Rust), then:

orcher workflow start order --task-queue quickstart-python --id order-1001 --input '"order-1001"'
orcher workflow result order-1001          # wait for it, and print what it returned
orcher workflow list                       # recent workflow executions
orcher workflow get order-1001             # one of them in detail
orcher workflow history order-1001         # every step the engine recorded
orcher logs order-1001 --follow            # its log, until it ends

Commands

Command What it does
orcher dev start|stop|status|logs Run a local engine in Docker: the quick local loop
orcher server start|stop|restart The same local engine with more control: an engine config file (--engine-config), an existing database (--database-url), the log level, a graceful stop
orcher server status|version Whether an engine (and a gateway, when configured) answers, and which versions are running
orcher workflow start <type> Start a workflow on --task-queue, with JSON --input; --wait for its result
orcher workflow result <id> Wait for a workflow to finish and print its result
orcher run <type>[@queue] -p key=value Start a workflow with parameters and follow it to the end
orcher workflow list List executions; filter with --type and --status, or --query
orcher workflow get <id> Status, timing, and result or error; --full adds pending tasks, timers and events
orcher workflow history <id> The journal: every step the engine recorded
orcher workflow tasks <id> The tasks the workflow ran, with attempts and durations
orcher workflow event <id> <name> Send an event, with an optional JSON --payload
orcher workflow cancel|terminate <id> Ask a workflow to stop, or stop it at once
orcher logs <id> A workflow's log; --follow until it ends, --journal or --tasks for the other views
orcher status A dashboard: where the CLI points, what answers, and workflow counts
orcher queue list|stats Workflows by task queue
orcher namespace ... list, get, create, update, deprecate, delete
orcher api-key create|list|get|revoke The engine's API keys: issue one with --scope (printed once), list, revoke at once
orcher batch ... Cancel, terminate, signal or reset many workflows at once, over the REST API
orcher auth login|logout|status Log in to ORCHER Cloud (browser device flow, token, or password)
orcher config ... Contexts: get-contexts, use-context, set-context, view, test-connection
orcher new python|typescript|rust <name> A new project on the published SDK: a workflow, a task, a worker, a starter and an end-to-end test
orcher new workflow <name> Add a workflow, with one task, to the project in this directory
orcher test Check the project here builds (--dry-run), or run its workflows end to end on the engine
orcher completion <shell> Shell completions for bash, zsh, fish, PowerShell and elvish

Run orcher <command> --help for every flag and more examples.


Where commands go

Flag Environment Default
--server ORCHER_SERVER the context's, else http://localhost:50051 The engine's gRPC address; https:// uses TLS
--api-url ORCHER_API_URL the context's api, else the --server host on port 8080 The REST API: the engine's HTTP port, or a cloud gateway. API keys, batch operations, log streaming, login
--context ORCHER_CONTEXT the current context A named environment from the config file
--config ORCHER_CONFIG ~/.orcher/config.yaml The config file
-n, --namespace ORCHER_NAMESPACE default The namespace to act in
ORCHER_API_KEY, ORCHER_TOKEN the context's stored login Credentials for an engine that requires them
ORCHER_CLOUD_URL https://api.orcher.io Where ORCHER Cloud is
ORCHER_CREDENTIAL_STORE the OS keychain file keeps logins in credentials beside the config file (owner-only), as happens anyway where there is no keychain
-o, --output table table, json, yaml or name

The local engine's ports are bound to 127.0.0.1: it runs without authentication unless its config file turns it on. Published anywhere else (--host 0.0.0.0), a current engine refuses to start without authentication, so turn it on in the file given with --config. orcher dev start and orcher server start take --engine-version (default 0.6.2) to run another engine release, and other ports when the defaults, 50051 and 8080, are taken.

Engines from 0.7.0 serve the dashboard on the HTTP port: orcher dev start lists it as Dashboard http://localhost:8080 (and orcher dev status -o json as engine.dashboard), --open opens it in a browser, and --no-ui starts the engine without it. It asks for no login while the engine runs without authentication.

A command that fails prints the reason to stderr and exits with status 1; so do workflow result and run for a workflow that failed, was canceled or terminated, or did not finish in time. Commands that would stop or delete something ask first; pass --force when there is no terminal to ask on.


Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for how to build, test and propose a change.

License

Licensed under the Apache License, Version 2.0.

Metadata

Release files for orcher 0.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for orcher 0.1.4
File Size Uploaded Provenance Actions
orcher-0.1.4.tar.gz 173.2 kB With provenance Details for orcher-0.1.4.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for orcher 0.1.4
File Actions
orcher-0.1.4-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for orcher-0.1.4-py3-none-win_amd64.whl
orcher-0.1.4-py3-none-musllinux_1_2_x86_64.whl Python 3 none Linux musl 1.2+ x86-64 Details for orcher-0.1.4-py3-none-musllinux_1_2_x86_64.whl
orcher-0.1.4-py3-none-musllinux_1_2_aarch64.whl Python 3 none Linux musl 1.2+ ARM64 Details for orcher-0.1.4-py3-none-musllinux_1_2_aarch64.whl
orcher-0.1.4-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for orcher-0.1.4-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
orcher-0.1.4-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for orcher-0.1.4-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
orcher-0.1.4-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for orcher-0.1.4-py3-none-macosx_11_0_arm64.whl
orcher-0.1.4-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for orcher-0.1.4-py3-none-macosx_10_12_x86_64.whl

Total release size: 46.4 MB

Release files / orcher-0.1.4.tar.gz

Download URL orcher-0.1.4.tar.gz
Size 173.2 kB
Tags Source
SHA-256 checksum
How to use checksums
2d3d2be7960556985b3afbc3e95b2b4e823726a61e7773f7c8ca9c3f5abce4a4
BLAKE2b-256 checksum
How to use checksums
f478df86cb3361310ed51e8df894007202f116e13168f82ca9312ffaeac92a83
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / orcher-0.1.4-py3-none-win_amd64.whl

Download URL orcher-0.1.4-py3-none-win_amd64.whl
Size 6.2 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
a0036e76f3658b447cfabbc10257a53ef39900d471a3c28bd0f977e7fb506dc7
BLAKE2b-256 checksum
How to use checksums
6a6bb2b185b4a49d3e8ef2eab5f2a8bf9fe4b6515478a33940454120aa2dcdfb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / orcher-0.1.4-py3-none-musllinux_1_2_x86_64.whl

Download URL orcher-0.1.4-py3-none-musllinux_1_2_x86_64.whl
Size 7.3 MB
Tags Linux musl 1.2+ x86-64 Python 3
SHA-256 checksum
How to use checksums
21fa5037be6062dac52349584e1a359e0006fa30290bf9f29c2a9a59da5da2e8
BLAKE2b-256 checksum
How to use checksums
8615620efe8a9248c8f98566cc4cc7373ef9fda42e429e7060f1bafaec33d425
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / orcher-0.1.4-py3-none-musllinux_1_2_aarch64.whl

Download URL orcher-0.1.4-py3-none-musllinux_1_2_aarch64.whl
Size 7.0 MB
Tags Linux musl 1.2+ ARM64 Python 3
SHA-256 checksum
How to use checksums
27d6769f33f4218021f75d1b4665c3b5be523703d6123f0a308a4bdb749c49aa
BLAKE2b-256 checksum
How to use checksums
284d3ffcef5c06e76d219ae2567a08c549870b9a126c5839f779375444b905a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / orcher-0.1.4-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL orcher-0.1.4-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 7.2 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
42495e131385e70647e0c28c04581106fec9be0ca227970c0556f1a14b6bcbca
BLAKE2b-256 checksum
How to use checksums
b0b994cbf37d8ea4ebc04ca38885e750c4763f625caa533240e5a96bf88dc9cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / orcher-0.1.4-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL orcher-0.1.4-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 7.0 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
3610a1a4e6ec4052794ee902afd6942f550b2d1dd873920aa950dbccd3f57a0b
BLAKE2b-256 checksum
How to use checksums
b6f6d551681da569a557af2adc9162ff0d446c32c1a81895b03aa054c55e037e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / orcher-0.1.4-py3-none-macosx_11_0_arm64.whl

Download URL orcher-0.1.4-py3-none-macosx_11_0_arm64.whl
Size 5.7 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
accbc21233851dd3fa91cd3b26bb6f4c5e5b78cd77f05e779c33268e4f4d3295
BLAKE2b-256 checksum
How to use checksums
20684af129941b5986df663efff185c202a28574d9508bf25b87ffe110cf8d9e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / orcher-0.1.4-py3-none-macosx_10_12_x86_64.whl

Download URL orcher-0.1.4-py3-none-macosx_10_12_x86_64.whl
Size 5.9 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
5ab25a3f008177d8338977719a45c835910b455691883634165a1b69a3d1a72c
BLAKE2b-256 checksum
How to use checksums
0bc59abdfb9d6066debfa8e1a6ba4a2b837a2a63aa06df06b11cd63f2ebecf5c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for orcher 0.1.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 8 files in this release have been uploaded with provenance metadata.

Select from 8 files

Attestation for orcher-0.1.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page