CLI for Conductor

Conductor is the leading open-source orchestration platform allowing developers to build highly scalable distributed applications.

Check out the official documentation for Conductor.

This repository provides a CLI for the Orkes Conductor Server.

⭐ Conductor OSS

Show support for the Conductor OSS. Please help spread the awareness by starring Conductor repo.


Installation

$3

``bash
brew tap conductor-oss/conductor
brew install orkes
`

Or in one line:

`bash
brew install conductor-oss/conductor/orkes
`

$3

If you have Node.js installed:

`bash
npm install -g @io-orkes/conductor-cli
`

This will automatically download and install the appropriate binary for your platform.

$3

Install the latest version using curl:

`bash
curl -fsSL https://raw.githubusercontent.com/conductor-oss/conductor-cli/main/install.sh | sh
`

This will automatically:
- Detect your OS and architecture
- Download the latest release
- Install to /usr/local/bin
- Verify the installation

$3

To install to a custom directory:

`bash
INSTALL_DIR=$HOME/.local/bin curl -fsSL https://raw.githubusercontent.com/conductor-oss/conductor-cli/main/install.sh | sh
`

$3

Download the appropriate binary for your platform from the releases page:

- Linux amd64: orkes_linux_amd64
- Linux arm64: orkes_linux_arm64
- macOS amd64: orkes_darwin_amd64
- macOS arm64: orkes_darwin_arm64
- Windows amd64: orkes_windows_amd64.exe
- Windows arm64: orkes_windows_arm64.exe

Then make it executable and move it to your PATH:

`bash
chmod +x orkes_*
mv orkes_* /usr/local/bin/orkes
`

$3

`bash
orkes --version
`

$3

Enable tab completion for commands, flags, and arguments:

Zsh (macOS default):
`bash


One-time setup

orkes completion zsh > $(brew --prefix)/share/zsh/site-functions/_orkes

Restart your shell or run:

source ~/.zshrc
`

Bash:
`bash


Linux

orkes completion bash > /etc/bash_completion.d/orkes

macOS

orkes completion bash > $(brew --prefix)/etc/bash_completion.d/orkes

Then restart your shell

`

Fish:
`bash
orkes completion fish > ~/.config/fish/completions/orkes.fish
`

PowerShell:
`powershell
orkes completion powershell | Out-String | Invoke-Expression
`

After installing, you'll get tab completion when typing orkes .

Configuration

The CLI connects to your Conductor server and can optionally persist configuration using the config save command.

$3

The CLI supports two types of Conductor servers:

- Enterprise (Orkes Conductor) (default): Requires server URL and authentication credentials
- OSS Conductor: Open-source Conductor - requires only server URL, no authentication

Use the --server-type flag to specify your server type (defaults to Enterprise):

`bash


Enterprise/Orkes Conductor (default)

orkes --server https://developer.orkescloud.com --auth-token your-token workflow list

OSS Conductor

orkes --server http://localhost:8080/api --server-type OSS workflow list
`

$3

The config save command provides an interactive setup that guides you through configuring your Conductor connection. It prompts you for:
- Server URL
- Server type (OSS or Enterprise)
- Authentication method (API Key + Secret or Auth Token for Enterprise)

If a configuration already exists, you can press Enter to keep existing values (credentials are masked as **).

Interactive Configuration:

`bash


Run interactive configuration

orkes config save

Example interaction:

Server URL [http://localhost:8080/api]: https://developer.orkescloud.com

Server type (OSS/Enterprise) [Enterprise]: ← Press Enter to keep

#

Authentication method:

1. API Key + Secret

2. Auth Token

Choose [1]: 2

Auth Token []: your-token-here

✓ Configuration saved to ~/.conductor-cli/config.yaml

`

Updating Existing Configuration:

When a configuration file already exists, the interactive prompts show your current values. Press Enter to keep them:

`bash
orkes config save

Example with existing config:

Server URL [https://developer.orkescloud.com]: ← Press Enter to keep

Server type (OSS/Enterprise) [Enterprise]: ← Press Enter to keep

#

Authentication method:

1. API Key + Secret

2. Auth Token

Choose [2]: ← Press Enter to keep

Auth Token [**]: ← Press Enter to keep or enter new token

`

Non-Interactive (Legacy):

You can still save configuration non-interactively by providing flags:

`bash


Enterprise with auth token (default server type)

orkes --server https://developer.orkescloud.com --auth-token your-token config save

Enterprise with API key + secret

orkes --server https://developer.orkescloud.com --auth-key your-key --auth-secret your-secret config save

OSS Conductor

orkes --server http://localhost:8080/api --server-type OSS config save
`

Once saved, you can run commands without providing flags:

`bash


After saving config, simply run:


orkes workflow list
`

Note: Server URLs can be provided with or without /api suffix (e.g., http://localhost:8080 or http://localhost:8080/api).

$3

Profiles allow you to manage multiple Conductor environments (e.g., development, staging, production) and easily switch between them.

Creating Profiles:

Use the --profile flag with config save to create named profiles. The command will run in interactive mode:

`bash


Interactively configure development profile

orkes config save --profile dev

Interactively configure staging profile

orkes config save --profile staging

Interactively configure production profile

orkes config save --profile production
`

You can also use the non-interactive method with flags:

`bash


Save Enterprise staging environment (default server type)

orkes --server https://staging.example.com --auth-token staging-token --profile staging config save

Save Enterprise production environment

orkes --server https://prod.example.com --auth-token prod-token --profile production config save

Save local OSS development environment

orkes --server http://localhost:8080/api --server-type OSS --profile dev config save
`

Using Profiles:

Switch between environments by specifying the profile:

`bash


Using --profile flag

orkes --profile production workflow list

Using ORKES_PROFILE environment variable

export ORKES_PROFILE=production
orkes workflow list

Flag takes precedence over environment variable

ORKES_PROFILE=staging orkes --profile production workflow list # Uses production
`

Profile File Structure:

`
~/.conductor-cli/
├── config.yaml # Default profile
├── config-production.yaml # Production profile
├── config-staging.yaml # Staging profile
└── config-dev.yaml # Development profile
`

Listing Profiles:

`bash


List all configuration profiles


orkes config list
`

This shows:
- default - for the default config.yaml file
- Profile names (e.g., production, staging) - for named profiles like config-production.yaml

Deleting Profiles:

`bash


Delete default config (with confirmation prompt)

orkes config delete

Delete named profile

orkes config delete production

Delete without confirmation using -y flag

orkes config delete production -y
`

Profile Error Handling:

If you reference a profile that doesn't exist, you'll get a clear error:

`bash
orkes --profile nonexistent workflow list


Error: Profile 'nonexistent' doesn't exist (expected file: ~/.conductor-cli/config-nonexistent.yaml)


`

$3

The CLI can be configured using command-line flags, environment variables, or a configuration file. Configuration is handled with the following precedence (highest to lowest):

1. Command-line flags
2. Environment variables
3. Configuration file

$3

You can override saved configuration by providing flags directly:

`bash


Override server URL for a single command

orkes --server http://different-server:8080/api workflow list

Use different auth token temporarily

orkes --auth-token temporary-token workflow list

Use OSS server type

orkes --server http://localhost:8080/api --server-type OSS workflow list
`

$3

Set these environment variables to configure the CLI without flags:

`bash


Server and authentication

export CONDUCTOR_SERVER_URL=http://localhost:8080/api
export CONDUCTOR_AUTH_TOKEN=your-auth-token

Or using API key + secret

export CONDUCTOR_SERVER_URL=http://localhost:8080/api
export CONDUCTOR_AUTH_KEY=your-api-key
export CONDUCTOR_AUTH_SECRET=your-api-secret

Server type (OSS or Enterprise, defaults to Enterprise)

export CONDUCTOR_SERVER_TYPE=OSS

Profile selection

export ORKES_PROFILE=production
`

#### Disabling Colored Output

If you want to disable color output for any reason (CI/CD, etc), you can use:

`bash
export NO_COLOR=1
`

Any non-null value in the NO_COLOR variable will disable colored output.

$3

Configuration files use YAML format and are stored in ~/.conductor-cli/:

`yaml


Example config.yaml for Enterprise with auth token (default)


server: https://developer.orkescloud.com/api
auth-token: your-auth-token
verbose: false
`

`yaml


Example config.yaml for Enterprise with API key + secret


server: https://developer.orkescloud.com/api
auth-key: your-api-key
auth-secret: your-api-secret
verbose: false
`

`yaml


Example config.yaml for OSS Conductor (no authentication)


server: http://localhost:8080/api
server-type: OSS
verbose: false
`

Notes:
- server-type defaults to Enterprise if not specified
- Enterprise requires one authentication method (auth-token OR auth-key+auth-secret)
- OSS Conductor doesn't require auth-token, auth-key, or auth-secret

You can also specify a custom config file location:

`bash
orkes --config /path/to/my-config.yaml workflow list
`

Workflow Metadata Management

`shell


List the workflows on the server

orkes workflow list

Get the workflows definition - fetches the latest version

orkes workflow get

or you can specify a version

orkes workflow get

You can use quotes for workflow name if the name contains spaces, comma or special characters

orkes workflow get ""

`


$3


`shell

Register a workflow stored in the file

orkes workflow create /path/to/workflow_definition.json --force # use --force to overwrite existing
`

API Gateway Management

The API Gateway feature allows you to expose Conductor workflows as REST APIs with authentication, CORS configuration, and route management.

$3

`shell


List all API Gateway services

orkes api-gateway service list

Get a specific service

orkes api-gateway service get

Create a service from JSON file

orkes api-gateway service create service.json

Create a service using command-line flags

orkes api-gateway service create \
--service-id my-service-id \
--name "Display Name" \
--path "/my-base-path" \
--description "A description of the service" \
--enabled \
--mcp-enabled \
--auth-config-id "token-based" \
--cors-allowed-origins "*" \
--cors-allowed-methods "GET,POST,PUT,DELETE,PATCH,OPTIONS" \
--cors-allowed-headers "*"

Update a service

orkes api-gateway service update service.json

Delete a service

orkes api-gateway service delete
`

Example service JSON:
`json
{
"id": "my-service-id",
"name": "Display Name",
"path": "/my-base-path",
"description": "A description of the service",
"enabled": true,
"mcpEnabled": true,
"authConfigId": "token-based",
"corsConfig": {
"accessControlAllowOrigin": ["*"],
"accessControlAllowMethods": ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
"accessControlAllowHeaders": ["*"]
}
}
`

CORS Configuration Notes:
- You can specify multiple values using comma-separated strings: --cors-allowed-origins "https://example.com,https://another.com"
- Or use the flag multiple times: --cors-allowed-origins "https://example.com" --cors-allowed-origins "https://another.com"

$3

`shell


List all authentication configurations

orkes api-gateway auth list

Get a specific auth config

orkes api-gateway auth get

Create an auth config from JSON file

orkes api-gateway auth create auth-config.json

Create an auth config using command-line flags

orkes api-gateway auth create \
--auth-config-id "token-based" \
--auth-type "API_KEY" \
--application-id "my-app-id" \
--api-keys "key1,key2,key3"

Update an auth config

orkes api-gateway auth update auth-config.json

Delete an auth config

orkes api-gateway auth delete
`

Example auth config JSON:
`json
{
"id": "token-based",
"authenticationType": "API_KEY",
"applicationId": "my-application-id",
"apiKeys": ["key1", "key2"]
}
`

$3

`shell


List all routes for a service

orkes api-gateway route list

Create a route for a service from JSON file

orkes api-gateway route create route.json

Create a route using command-line flags

orkes api-gateway route create my-service \
--http-method "GET" \
--path "/users/{userId}" \
--description "Get user by ID" \
--workflow-name "get_user_workflow" \
--workflow-version 1 \
--execution-mode "SYNC"

Create a route with additional options

orkes api-gateway route create my-service \
--http-method "POST" \
--path "/orders" \
--description "Create new order" \
--workflow-name "create_order_workflow" \
--workflow-version 2 \
--execution-mode "ASYNC" \
--request-metadata-as-input \
--workflow-metadata-in-output

Update a route

orkes api-gateway route update route.json

Delete a route

orkes api-gateway route delete
`

Example route JSON:
`json
{
"path": "/users/{userId}",
"httpMethod": "GET",
"description": "Get user by ID",
"workflowExecutionMode": "SYNC",
"mappedWorkflow": {
"name": "get_user_workflow",
"version": 1
}
}
`

Workers

⚠️ EXPERIMENTAL FEATURES

The CLI supports two types of workers for processing Conductor tasks:

$3

Execute tasks using external programs written in any language (Python, Node.js, Go, Rust, shell scripts, etc.).

The CLI polls for tasks and passes them to your worker via stdin/stdout.

Best for: Complex logic, heavy dependencies, full language ecosystem access

👉 Complete Stdio Worker Documentation →

Quick example:
`bash


Run a Python worker (continuous polling with parallel execution)

orkes worker stdio --type greet_task python3 worker.py

Poll multiple tasks per batch for higher throughput

orkes worker stdio --type greet_task python3 worker.py --count 5
`

$3

Execute tasks using JavaScript scripts with built-in utilities (HTTP, crypto, string functions). No external dependencies needed.

Best for: Prototyping, Lightweight tasks, quick scripts, HTTP integrations

👉 Complete JavaScript Worker Documentation →

Quick example:
`bash


Run a JavaScript worker


orkes worker js --type greet_task worker.js
`

$3

⚠️ EXPERIMENTAL - Download and execute workers directly from your Orkes Conductor instance without managing local files.

Remote workers are stored in the Orkes Conductor job-runner registry and can be generated using the AI Assistant in your Orkes instance. Once created, workers are automatically downloaded, cached locally, and executed with all dependencies installed.

Best for: Team collaboration, centralized worker management, zero local setup

Key features:
- Zero configuration: No manual worker setup or file management
- Automatic dependencies: Python workers get a virtual environment with all dependencies installed automatically (including conductor-python SDK)
- Smart caching: Workers are cached locally after first download for fast startup
- Multi-language support: JavaScript (Node.js) and Python workers supported
- Version control: Workers are versioned and can be updated centrally

Quick examples:
`bash


List available workers in your Orkes instance

orkes worker list-remote

Run a remote worker (downloads and caches automatically)

orkes worker remote --type greet_task

Force refresh to get latest version

orkes worker remote --type greet_task --refresh

Run with batch processing for higher throughput

orkes worker remote --type greet_task --count 10
`

How it works:
1. Create workers using the AI Assistant in your Orkes Conductor instance
2. Workers are stored in the job-runner registry with all metadata and dependencies
3. CLI downloads worker code on first run and sets up the environment automatically
4. Subsequent runs use the cached worker for instant startup
5. Python workers get an isolated virtual environment with dependencies installed
6. Workers authenticate automatically using your CLI configuration

Note: Remote workers must exist in your Orkes Conductor instance. Currently, workers are generated by the AI Assistant feature in Orkes Conductor.

Exit Codes

The CLI uses standard exit codes for error handling:

| Exit Code | Description |
|-----------|-------------|
| 0 | Command completed successfully |
| 1 | General error (connection failed, authentication error, resource not found, etc.) |

Example usage in scripts:
`bash
if orkes execution start --workflow my_workflow; then
echo "Workflow started successfully"
else
echo "Failed to start workflow" >&2
exit 1
fi
`

Error Handling

Common errors and solutions:

$3


`
Error: Get "https://...": dial tcp: no such host
`
Solution: Verify your --server URL or CONDUCTOR_SERVER_URL environment variable

$3

`
Error: 401 Unauthorized
`
Solution: Check your authentication credentials (--auth-token or --auth-key/--auth-secret)

$3

`
Error: 404 Not Found
`
Solution: Verify the resource name or ID exists on the server

$3

`
Error: Profile 'prod' doesn't exist (expected file: ~/.conductor-cli/config-prod.yaml)
`
Solution: Create the profile using --save-config=prod` or verify the profile name

For AI Assistants & LLMs

For a concise, LLM-optimized reference with command tables, exit codes, and canonical examples, see CLAUDE.md.