CLI Reference¶
Complete reference for the Open Resource Broker command-line interface.
Global Options¶
Available for all commands:
| Flag | Description | Example |
|---|---|---|
--config |
Configuration file path | --config /path/to/config.json |
--log-level |
Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
--log-level DEBUG |
--format |
Output format (json, yaml, table, list) |
--format table |
--output |
Write output to file instead of stdout | --output results.json |
--quiet |
Suppress non-essential output | --quiet |
--verbose |
Enable verbose output | --verbose |
--no-color |
Disable colored output | --no-color |
--dry-run |
Show what would be done without executing | --dry-run |
--yes, -y |
Assume yes to all prompts | --yes |
--all |
Apply operation to all resources | --all |
--limit |
Maximum number of results to return | --limit 50 |
--offset |
Number of results to skip (for pagination) | --offset 100 |
--filter |
Filter using field=value, field~value, or field=~regex. Repeatable (AND logic). |
--filter "status=running" |
--region |
AWS region override | --region us-west-2 |
--profile |
AWS profile override | --profile production |
--scheduler |
Override scheduler strategy (default, hostfactory, slurm) |
--scheduler hostfactory |
--provider-name |
Override provider instance by name | --provider-name aws_prod_us-east-1 |
--completion |
Generate shell completion script (bash, zsh) |
--completion bash |
--version |
Show version and exit | --version |
Paging through long lists¶
machines list, requests list and requests list-returns (and the REST and SDK list calls) return a next_cursor when more results remain; in the table and list formats the CLI prints it on stderr as next cursor: <token>. Pass it back with --cursor (only these three commands accept it; it overrides --offset) to get the next page.
A cursor continues after the last row of the previous page, ordered by the sort value and the id. Rows added or removed elsewhere in the list between pages therefore do not cause repeats or gaps, as long as the sort value of the rows already returned does not change (a row whose status or launch time changes between pages can still move). A cursor is only valid for the filters and sort it was issued for; a malformed cursor or one from a different query is rejected instead of silently starting over. Cursors from earlier releases keep working.
With SQL storage the database filters, orders and cuts the page for plain equality filters (status, provider type, and for machines the request, for requests the template, request type and provider name) when sorting by a status, id or creation time column; sorting machines by launch_time (the default) is done in the database on SQLite only. With JSON or DynamoDB storage, with other dialects or sorts, and for q or --filter expressions, every page still loads and sorts the full result set, so paging there does not reduce memory or latency. The total count of a database page still scans the filtered rows, so the saving is memory rather than time.
HostFactory Compatibility¶
| Flag | Description | Example |
|---|---|---|
-f, --file |
Input JSON file path | -f request.json |
-d, --data |
Input JSON data string | -d '{"template":"aws-basic"}' |
Commands by Resource¶
Templates¶
Manage compute templates.
templates list¶
List all available templates.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --provider-api | Filter by provider API type | --provider-api EC2Fleet |
| --long | Include detailed configuration fields | --long |
| --format | Output format (json, yaml, table, list) | --format table |
Examples:
# List all templates
orb templates list
# List with details in table format
orb templates list --long --format table
# Filter by provider API
orb templates list --provider-api EC2Fleet
templates show¶
Show detailed information about a specific template.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| TEMPLATE_ID | Template ID to show (positional) | Yes* |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --template-id, -t | Template ID to show (flag) | --template-id aws-basic |
| --format | Output format | --format yaml |
Examples:
# Using positional argument
orb templates show aws-basic
# Using flag
orb templates show --template-id aws-basic
# With YAML output
orb templates show aws-basic --format yaml
templates create¶
Create a new template from a configuration file.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --file | Template configuration file | --file template.json |
| --validate-only | Only validate, do not create | --validate-only |
Examples:
# Create template
orb templates create --file new-template.json
# Validate only
orb templates create --file template.json --validate-only
templates update¶
Update an existing template.
Usage:
orb templates update [TEMPLATE_ID] --file FILE [OPTIONS]
orb templates update --template-id TEMPLATE_ID --file FILE [OPTIONS]
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| TEMPLATE_ID | Template ID to update (positional) | Yes* |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --template-id, -t | Template ID to update (flag) | --template-id aws-basic |
| --file | Updated template configuration file | --file updated.json |
Examples:
# Using positional argument
orb templates update aws-basic --file updated.json
# Using flag
orb templates update --template-id aws-basic --file updated.json
templates delete¶
Delete a template.
Usage:
orb templates delete [TEMPLATE_ID] [OPTIONS]
orb templates delete --template-id TEMPLATE_ID [OPTIONS]
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| TEMPLATE_ID | Template ID to delete (positional) | Yes* |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --template-id, -t | Template ID to delete (flag) | --template-id old-template |
| --force | Force deletion without confirmation | --force |
Examples:
# Using positional argument
orb templates delete old-template
# Using flag with force
orb templates delete --template-id old-template --force
templates validate¶
Validate a template configuration file.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --file | Template file to validate | --file template.json |
templates refresh¶
Refresh template cache and reload from files.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --force | Force complete refresh | --force |
templates generate¶
Generate example templates for providers.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --provider-name | Generate for specific provider instance | --provider-name aws_prod_us-east-1 |
| --all-providers | Explicitly generate for all active providers | --all-providers |
| --provider-api | Specific provider API | --provider-api EC2Fleet |
Examples:
# Generate for all active providers (default)
orb templates generate
# Generate for specific provider
orb templates generate --provider-name aws_prod_us-east-1
# Generate for specific API
orb templates generate --provider-api SpotFleet
Machines¶
Manage compute instances.
machines list¶
List all machines.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --status | Filter by machine status (specific filter) | --status running |
| --template-id | Filter by template ID (specific filter) | --template-id aws-basic |
| --timestamp-format | Timestamp format: auto, unix, iso | --timestamp-format iso |
| --filter | Generic filter: field=value, field~value, field=~regex. Repeatable (AND logic). | --filter "machine_types~t3" |
| --format | Output format | --format table |
Filter Examples:
# Filter by machine type substring
orb machines list --filter "machine_types~t3"
# Exact match on a field
orb machines list --filter "status=running"
# Regex match
orb machines list --filter "machine_id=~i-[0-9a-f]{17}"
# Combine multiple filters (AND logic)
orb machines list --filter "status=running" --filter "machine_types~t3"
# Mix specific and generic filters
orb machines list --status running --filter "machine_types~t3"
machines show¶
Show machine details.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| MACHINE_ID | Machine ID to show (positional) | Yes* |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --machine-id, -m | Machine ID to show (flag) | --machine-id i-1234567890abcdef0 |
| --format | Output format | --format yaml |
machines request¶
Request new machines.
Usage:
orb machines request [TEMPLATE_ID] [COUNT] [OPTIONS]
orb machines request --template-id TEMPLATE_ID --count COUNT [OPTIONS]
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| TEMPLATE_ID | Template ID to use (positional) | Yes |
| COUNT | Number of machines to request (positional) | Yes |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --template-id, -t | Template ID to use (flag) | --template-id aws-basic |
| --count, -c | Number of machines to request (flag) | --count 5 |
| --wait | Wait for machines to be ready | --wait |
| --timeout | Wait timeout in seconds | --timeout 600 |
Examples:
# Using positional arguments
orb machines request aws-basic 3
# Using flags
orb machines request --template-id aws-basic --count 3
# With wait and timeout
orb machines request aws-basic 5 --wait --timeout 600
machines return¶
Return (terminate) machines.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| MACHINE_IDS | Machine IDs to return (positional) | Yes* |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --force | Force return without confirmation | --force |
machines status¶
Check machine status.
Usage:
orb machines status MACHINE_IDS...
orb machines status --machine-id MACHINE_ID [--machine-id MACHINE_ID...] [OPTIONS]
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| MACHINE_IDS | Machine IDs to check (positional) | Yes* |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --machine-id, -m | Machine ID to check (flag, repeatable) | --machine-id i-abc --machine-id i-def |
machines terminate¶
Terminate (return) machines. Alias for machines return.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| MACHINE_IDS | Machine IDs to terminate (positional) | Yes* |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --force | Force termination without confirmation | --force |
Examples:
machines stop¶
Stop running machines.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| MACHINE_IDS | Machine IDs to stop (positional) | Yes* |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --force | Force stop without confirmation | --force |
Examples:
machines start¶
Start stopped machines.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| MACHINE_IDS | Machine IDs to start (positional) | Yes* |
Examples:
Requests¶
Manage provisioning requests.
requests list¶
List all requests.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --status | Filter by request status (specific filter) | --status pending |
| --template-id | Filter by template ID (specific filter) | --template-id aws-basic |
| --filter | Generic filter: field=value, field~value, field=~regex. Repeatable (AND logic). | --filter "template_id~spot" |
| --format | Output format | --format table |
Status Values:
- pending - Request submitted but not started
- in_progress - Request being processed
- completed - Request completed successfully
- failed - Request failed
- cancelled - Request cancelled
- partial - Request partially completed
- timeout - Request timed out
Filter Examples:
# Filter by status
orb requests list --status pending
# Generic filter by template ID substring
orb requests list --filter "template_id~spot"
# Combine filters (AND logic)
orb requests list --status in_progress --filter "template_id~ec2fleet"
requests show¶
Show details for a specific request.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| REQUEST_ID | Request ID to show (positional) | Yes* |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format yaml |
Examples:
requests cancel¶
Cancel a request.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| REQUEST_ID | Request ID to cancel | Yes |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --force | Force cancellation | --force |
Cancelling a request that has not settled stops its provisioning at the provider first, whether or not any machine has been recorded yet, and then returns the machines it already has. A fleet that is still fulfilling a partially filled request is stopped too, so it cannot keep launching capacity after the request reads cancelled. A partial or timeout request is aborted the same way and keeps reporting its true status; a completed, failed or cancelled request is left as it is.
The output lists what happened to each resource in provider_abort:
| Outcome | Meaning |
|---|---|
aborted |
The provider stopped the resource. |
already_gone |
The resource was already deleted or never existed. Cancelling again is safe. |
unsupported |
The provider cannot abort in-flight provisioning; the machines are still returned. |
If any resource cannot be stopped the command fails with a non-zero exit code and the request keeps its current state, so the cancel can be repeated. Resources that were already stopped report already_gone on the retry. The command exits 0 whenever the cancel took effect, including for a partial or timeout request whose resources were aborted.
How each provider API is stopped is described in the AWS provider pages: EC2 Fleet, Spot Fleet, Auto Scaling group and RunInstances.
requests confirm-terminated¶
Record that machines of a return request are terminated, for instances the
provider reports as not found. The provider is asked whether each machine is
gone; machines it confirms are recorded as verified. If it still shows a
machine, or cannot tell, the command fails unless --force is given, which
records the unverified machines as operator_attested. Providers with no
termination check always need --force. See also
Confirm termination.
Usage:
orb requests confirm-terminated REQUEST_ID --machine-id ID [--machine-id ID...] --reason TEXT [--force]
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --machine-id, -m | Machine verified terminated (required, repeatable, at most 100) | -m ocid1.instance.oc1... |
| --reason | Why the machines are known to be terminated (required, up to 500 characters) | --reason "deleted in console" |
| --force | Record machines the provider cannot verify as operator-attested | --force |
The operator is recorded as cli:<user>@<host>; this comes from the local
environment and is advisory only. Exits 1 when a machine is not part of the
request, the request is not a return request in progress, the provider still shows
an instance that is not terminated, or the provider cannot verify a machine and
--force was not given.
requests status¶
Check request status.
Usage:
orb requests status [REQUEST_IDS...] [OPTIONS]
orb requests status --request-id REQUEST_ID [--request-id REQUEST_ID...] [OPTIONS]
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| REQUEST_IDS | Request IDs to check (positional) | Yes* |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --request-id, -r | Request ID to check (flag, repeatable) | --request-id req-123 --request-id req-456 |
Examples:
# Using positional arguments
orb requests status req-123 req-456
# Using flags
orb requests status --request-id req-123 --request-id req-456
# Mixed usage
orb requests status req-123 --request-id req-456
Exit codes: with the default scheduler the command exits 1 if any requested request is failed, cancelled, timed out or partial, or cannot be found, and 0 otherwise. With the HostFactory scheduler it always exits 0; read the outcome from the JSON output.
System¶
System operations and health checks.
system status¶
Show system status.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format table |
system health¶
Run health check.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --detailed | Show detailed health information | --detailed |
system metrics¶
Show system metrics.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format table |
Server¶
Process lifecycle for the local ORB daemon (REST API + optional embedded UI).
orb system * is for remote API observability (status/health/metrics/reload of a
running ORB). orb server * manages the local process itself.
server start¶
Start the ORB server. Daemonised by default; pass --foreground to keep it in
the current shell (useful for containers, systemd Type=simple, and dev).
Usage:
Options:
| Flag | Description | Default | Example |
|------|-------------|---------|---------|
| --foreground, -F | Run in the foreground instead of daemonising | false | --foreground |
| --api-only | Skip the embedded UI even if ui.enabled=true | false | --api-only |
| --host | Server host (overrides config) | from config | --host localhost |
| --port | Server port (overrides config) | from config | --port 9000 |
| --workers | Number of workers | from config | --workers 4 |
| --reload | Enable uvicorn auto-reload (dev only) | false | --reload |
| --server-log-level | Server log level | from config | --server-log-level debug |
| --socket-path | Unix domain socket path (alternative to host/port) | none | --socket-path /tmp/orb.sock |
server stop¶
Stop the running ORB server. Sends SIGTERM, waits up to the configured
stop_timeout_seconds, then escalates to SIGKILL. The whole process group
is signalled so the embedded Reflex tree (Node/Next included) terminates with
the parent.
server status¶
Report PID, liveness, and a best-effort /health probe.
server restart¶
stop followed by start. Accepts the same flags as start.
server reload¶
Send SIGHUP to the running daemon.
server logs¶
Tail the daemon log file (<log_dir>/orb-server.log by default).
Config¶
Configuration management.
config show¶
Show configuration.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format yaml |
config set¶
Set configuration value.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| KEY | Configuration key | Yes |
| VALUE | Configuration value | Yes |
config get¶
Get configuration value.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| KEY | Configuration key | Yes |
config validate¶
Validate configuration.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --file | Configuration file to validate | --file config.json |
Providers¶
Provider management and operations.
providers list¶
List available providers.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format table |
| --detailed | Show detailed provider information | --detailed |
providers show¶
Show provider details.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format yaml |
| --provider-name | Show specific provider details | --provider-name aws_prod_us-east-1 |
providers health¶
Check provider health.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format table |
| --provider-name | Check specific provider health | --provider-name aws_prod_us-east-1 |
providers add¶
Add a new provider instance.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --name | Provider instance name | --name aws-prod |
| --aws-profile | AWS profile name | --aws-profile production |
| --aws-region | AWS region | --aws-region us-east-1 |
| --discover | Discover infrastructure after adding | --discover |
Examples:
orb providers add --name aws-prod --aws-profile production --aws-region us-east-1
orb providers add --name aws-dev --aws-profile dev --aws-region us-west-2 --discover
providers remove¶
Remove a provider instance.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| PROVIDER_NAME | Provider instance name to remove | Yes |
Examples:
providers update¶
Update provider configuration.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| PROVIDER_NAME | Provider instance name | Yes |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --aws-region | Update region | --aws-region eu-west-1 |
| --aws-profile | Update profile | --aws-profile new-profile |
Examples:
orb providers update aws-prod --aws-region eu-west-1
orb providers update aws-prod --aws-profile updated-profile
providers set-default¶
Set the default provider instance.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| PROVIDER_NAME | Provider name to set as default | Yes |
Examples:
providers get-default¶
Show the current default provider.
Usage:
Examples:
providers select¶
Select provider strategy.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| PROVIDER | Provider name to select | Yes |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --strategy | Specific strategy to select | --strategy ec2fleet |
providers exec¶
Run a provider-side maintenance operation. exec accepts only operator-safe operations; operations that create, start, stop or terminate machines have their own commands and are refused here. Today the only operation is cleanup-orphaned-resources.
Usage:
Arguments:
| Argument | Description | Required |
|----------|-------------|----------|
| OPERATION | Operation to execute, in kebab-case or snake_case | Yes, unless --list is used |
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --provider-name | Provider instance to run the operation on | --provider-name aws_prod_us-east-1 |
| --list | List the operations each provider instance supports instead of running one | --list |
| --dry-run | Ask the operation to report what it would do without changing anything | --dry-run |
| --param | Operation parameter as KEY=VALUE; repeat for several. Values are read as JSON when possible | --param min_age_hours=48 |
| --params | Operation parameters as a JSON object | --params '{"min_age_hours":48}' |
A provider that does not declare the operation causes exit code 1 and a message listing what it does support. orb providers show also lists a provider instance's supported_operations.
cleanup-orphaned-resources (AWS)¶
Delete the launch templates ORB created that nothing uses any more. This is an explicit maintenance operation; ORB never runs it in the background.
orb providers exec cleanup-orphaned-resources --provider-name aws_prod_us-east-1 --dry-run
orb providers exec cleanup-orphaned-resources --provider-name aws_prod_us-east-1 --param min_age_hours=48
| Parameter | Description |
|---|---|
min_age_hours |
Only consider templates at least this old (default 24, minimum 1) |
force |
Allow min_age_hours below 1. A template created moments ago may belong to a request that has not launched anything yet, so this can delete a template that request still needs. Example: --param force=true --param min_age_hours=0 |
A template is deleted only if it carries the orb:managed-by tag, has exactly the name ORB generates for it (the resource prefix, its orb:request-id tag, -, its orb:template-id tag), is old enough, has no pending, running, stopping or stopped instance, and is not referenced by an active Auto Scaling group, EC2 Fleet or Spot Fleet request. The operation does nothing when cleanup.enabled or cleanup.delete_launch_template is false in the provider configuration, and cleanup.dry_run makes it a dry run.
The sweep covers all ORB-generated templates in the account and region of the selected provider instance, so other regions need a run per provider instance. The orb:managed-by tag has the same value for every ORB installation, so the sweep also sees templates created by other ORB installations that share the account and region, and deletes the unused ones among them. Templates whose name ORB did not generate are always kept, even when they carry ORB tags.
The result names the provider, region and account_id the sweep ran against. When more than one provider is configured, a run that changes anything needs an explicit --provider-name; a --dry-run may use the default provider. Boolean parameters (force) accept true or false only, and unknown parameters are rejected. If cleanup.enabled or cleanup.delete_launch_template is false, the command exits non-zero and says so.
Every template is judged before the first one is deleted. If a lookup fails, the command exits non-zero and nothing has been deleted. If a delete fails part-way, the command exits non-zero and the output lists the templates in deleted, failed (with the error) and kept (with the reason), so the result is never reported as all-or-nothing when it was not. The permissions it needs are listed in the IAM permissions guide.
providers metrics¶
Show provider metrics.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format table |
| --provider-name | Show metrics for specific provider | --provider-name aws_prod_us-east-1 |
Health fields:
health_statusis the result of a live health probe of the named provider:healthy,unhealthy(the provider reported a problem, the probe failed, or it timed out after 5 seconds) orunknown(no provider name given, or the provider could not be found). Results are reused for 30 seconds, so repeated calls do not each hit the provider API.health_sample_countis the number of live probes run for that provider since the process started.uptime_percentisnull. ORB does not run continuous probes, so it does not report an uptime figure.
Storage¶
Storage management and operations.
storage list¶
List available storage strategies.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format table |
storage show¶
Show current storage configuration.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format yaml |
| --strategy | Show specific storage strategy details | --strategy json |
storage validate¶
Validate storage configuration.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --strategy | Validate specific storage strategy | --strategy json |
storage test¶
Test storage connectivity.
Usage:
Options:
| Flag | Description | Default | Example |
|------|-------------|---------|---------|
| --strategy | Test specific storage strategy | | --strategy json |
| --timeout | Test timeout in seconds | 30 | --timeout 60 |
storage health¶
Check storage health.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format table |
| --detailed | Show detailed health information | --detailed |
storage metrics¶
Show storage performance metrics.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format table |
| --strategy | Show metrics for specific storage strategy | --strategy json |
Scheduler¶
Scheduler management and configuration.
scheduler list¶
List available scheduler strategies.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format table |
| --long | Show detailed information | --long |
scheduler show¶
Show scheduler configuration.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format yaml |
| --scheduler | Show specific scheduler strategy details | --scheduler hostfactory |
scheduler validate¶
Validate scheduler configuration.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --format | Output format | --format table |
| --scheduler | Validate specific scheduler strategy | --scheduler default |
MCP (Model Context Protocol)¶
MCP operations for AI assistant integration.
The MCP tools are derived from the operation catalog, so the same operations the CLI, REST, and SDK expose are available to MCP clients. Introspecting the live tool set (listing and calling tools interactively) is the job of an MCP client or the MCP Inspector, not a server-side command.
mcp serve¶
Start the MCP server. Defaults to stdio, the transport local MCP clients expect;
pass --transport http to serve over Streamable HTTP.
Usage:
Options:
| Flag | Description | Default | Example |
|------|-------------|---------|---------|
| --transport | Transport to serve over (stdio, http; streamable-http is an alias for http) | stdio | --transport http |
| --host | Host to bind for the http transport | 127.0.0.1 | --host 0.0.0.0 |
| --port | Port to bind for the http transport | 8000 | --port 4000 |
| --path | URL path to mount for the http transport | /mcp | --path /mcp |
mcp validate¶
Check the MCP tool set offline: verifies every catalog operation exposed on the MCP interface produces a tool with a resolvable input schema. Runs without starting a server or client, so it is safe in CI.
Usage:
Reports the tool count and names, exiting non-zero if any tool fails to resolve.
Infrastructure¶
Discover and manage AWS infrastructure (VPCs, subnets, security groups) used by ORB.
See infrastructure-commands.md for full documentation.
infrastructure discover¶
Scan your AWS account for available VPCs, subnets, and security groups.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --show | Show specific resources: vpcs, subnets, security-groups (or sg), or all | --show subnets |
| --summary | Show only summary counts, no details | --summary |
| --all-providers | Discover across all providers | --all-providers |
infrastructure show¶
Display the infrastructure ORB is currently configured to use.
Usage:
infrastructure validate¶
Verify that the configured infrastructure still exists in AWS.
Usage:
Init¶
Initialize ORB configuration.
init¶
Initialize ORB configuration.
Usage:
Options:
| Flag | Description | Example |
|------|-------------|---------|
| --non-interactive | Non-interactive mode | --non-interactive |
| --force | Force overwrite existing config | --force |
| --scheduler | Scheduler type | --scheduler hostfactory |
| --provider-type | Provider type | --provider-type aws |
| --region | AWS region | --region us-west-2 |
| --profile | AWS profile | --profile production |
| --config-dir | Custom configuration directory | --config-dir /custom/config |
| --subnet-ids | Comma-separated subnet IDs for template_defaults (non-interactive only) | --subnet-ids subnet-aaa,subnet-bbb |
| --security-group-ids | Comma-separated security group IDs for template_defaults (non-interactive only) | --security-group-ids sg-111,sg-222 |
| --fleet-role | Spot Fleet IAM role ARN or name for template_defaults (non-interactive only) | --fleet-role arn:aws:iam::123456789012:role/SpotFleetRole |
Notes:
- --subnet-ids, --security-group-ids, and --fleet-role are only used with --non-interactive. In interactive mode, ORB discovers these values from your AWS account automatically.
- These values are stored in template_defaults in config.json and applied at runtime when provisioning machines — they are not baked into template files.
Examples:
# Interactive init (discovers infrastructure from AWS)
orb init --scheduler hostfactory --provider-type aws --region us-east-1
# Non-interactive init with pre-known infrastructure values
orb init --non-interactive --region us-east-1 \
--subnet-ids subnet-aaa111,subnet-bbb222 \
--security-group-ids sg-11111111 \
--fleet-role arn:aws:iam::123456789012:role/SpotFleetRole
Argument Patterns¶
Positional vs Flag Arguments¶
Many commands support both positional and flag arguments for flexibility:
Templates¶
# Both work the same
orb templates show aws-basic
orb templates show --template-id aws-basic
orb templates delete old-template
orb templates delete --template-id old-template
Machines¶
# Both work the same
orb machines show i-1234567890abcdef0
orb machines show --machine-id i-1234567890abcdef0
orb machines request aws-basic 5
orb machines request --template-id aws-basic --count 5
Requests¶
# Multiple request IDs - both patterns work
orb requests status req-123 req-456 req-789
orb requests status --request-id req-123 --request-id req-456 --request-id req-789
# Mixed usage also works
orb requests status req-123 --request-id req-456
Required Arguments¶
Arguments marked with * in the tables above are required, but can be provided either as positional arguments OR as flags (not both).
Global Overrides¶
Scheduler Override¶
Use --scheduler to override the configured scheduler for any command:
# Use HostFactory scheduler for this command
orb --scheduler hostfactory templates list
# Use default scheduler for this command
orb --scheduler default machines request aws-basic 3
# Use Slurm scheduler for this command
orb --scheduler slurm requests status req-123
Available Schedulers:
- default - Native domain format, CLI-friendly output
- hostfactory - IBM Spectrum Symphony (HostFactory) compatible format
- slurm - Slurm scheduler integration
Provider Override¶
Use --provider-name to override the selected provider instance for any command:
# Use specific provider instance
orb --provider-name aws_prod_us-east-1 templates list
# Override for machine requests
orb --provider-name aws_dev_us-east-1 machines request template-id 3
# Combined with scheduler override
orb --scheduler hostfactory --provider-name aws_prod_us-east-1 requests status req-123
Provider Instance Names:
Provider instances are defined in your configuration file. Common patterns:
- aws_prod_us-east-1 - AWS production profile in US East 1
- aws_dev_us-east-1 - AWS development profile in US East 1
- aws_staging_us-west-2 - AWS staging profile in US West 2
- aws_default_eu-west-1 - AWS default profile in EU West 1
Use orb providers list to see available provider instances.
Multi-Provider Template Generation¶
The templates generate command supports generating templates for multiple providers:
Default Behavior¶
Provider-Specific Generation¶
# Generate for specific provider instance
orb templates generate --provider-name aws_prod_us-east-1
# Generate for specific provider API
orb templates generate --provider-api EC2Fleet
# Explicitly generate for all providers
orb templates generate --all-providers
Provider Naming Conventions¶
Templates are generated using provider-specific naming patterns:
AWS Provider Pattern: {type}_{profile}_{region}
- Example: aws_prod_us-west-2
- Components: provider type + AWS profile + AWS region
Template Files Generated:
- {provider-name}_templates.json - Main template file
- One file per active provider instance
Output Formats¶
All commands support multiple output formats via --format:
| Format | Description | Best For |
|---|---|---|
json |
JSON format (default) | Scripting, APIs |
yaml |
YAML format | Human-readable config |
table |
Rich table format | Terminal viewing |
list |
Simple list format | Quick scanning |
Examples:
# JSON output (default)
orb templates list
# Table format for terminal
orb templates list --format table
# YAML for configuration
orb config show --format yaml
# List for simple output
orb providers list --format list
Exit Codes¶
Commands return appropriate exit codes for scripting:
| Code | Meaning | Example |
|---|---|---|
0 |
Success | Request completed, command succeeded |
1 |
Failure | Request failed, validation error, command error |
Scheduler-Aware Exit Codes:
- HostFactory: Request creation and return commands return 1 for failed/cancelled/timeout/partial requests. requests status always returns 0 and reports the outcome in its JSON output, because HostFactory treats a non-zero exit from the status script as a script failure.
- Default: requests status returns 1 if any requested request is failed, cancelled, timed out or partial, or cannot be found.
Environment Variables¶
Standard ORB Variables¶
ORB_CONFIG_DIR- Configuration directoryORB_WORK_DIR- Working directoryORB_LOG_DIR- Log directoryORB_LOG_LEVEL- Log level (DEBUG, INFO, WARNING, ERROR)
HostFactory Variables (when using HostFactory scheduler)¶
HF_PROVIDER_CONFDIR- HostFactory config directoryHF_PROVIDER_WORKDIR- HostFactory work directoryHF_PROVIDER_LOGDIR- HostFactory log directoryHF_LOGLEVEL- HostFactory log levelHF_LOGGING_CONSOLE_ENABLED- Enable/disable console logging
Shell Completion¶
Generate shell completion scripts:
# Bash completion
orb --completion bash > /etc/bash_completion.d/orb
# Zsh completion
orb --completion zsh > ~/.zsh/completions/_orb
Examples¶
Basic Workflow¶
# Initialize configuration
orb init --scheduler hostfactory --provider-type aws --region us-east-1
# Generate example templates
orb templates generate
# List available templates
orb templates list --format table
# Request machines
orb machines request aws-basic 3
# Check request status
orb requests status req-123
# Check system health
orb system health --detailed
Multi-Provider Setup¶
# Generate templates for all providers
orb templates generate --all-providers
# Use specific provider
orb --provider-name aws_prod_us-east-1 machines request template-id 5
# Check provider health
orb providers health --provider-name aws_prod_us-east-1