Skip to content

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:

orb templates list [OPTIONS]

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:

orb templates show [TEMPLATE_ID] [OPTIONS]
orb templates show --template-id TEMPLATE_ID [OPTIONS]

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:

orb templates create --file FILE [OPTIONS]

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:

orb templates validate --file FILE

Options: | Flag | Description | Example | |------|-------------|---------| | --file | Template file to validate | --file template.json |

templates refresh

Refresh template cache and reload from files.

Usage:

orb templates refresh [OPTIONS]

Options: | Flag | Description | Example | |------|-------------|---------| | --force | Force complete refresh | --force |

templates generate

Generate example templates for providers.

Usage:

orb templates generate [OPTIONS]

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:

orb machines list [OPTIONS]

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:

orb machines show [MACHINE_ID] [OPTIONS]
orb machines show --machine-id MACHINE_ID [OPTIONS]

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:

orb machines return [MACHINE_IDS...] [OPTIONS]

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:

orb machines terminate [MACHINE_IDS...] [OPTIONS]

Arguments: | Argument | Description | Required | |----------|-------------|----------| | MACHINE_IDS | Machine IDs to terminate (positional) | Yes* |

Options: | Flag | Description | Example | |------|-------------|---------| | --force | Force termination without confirmation | --force |

Examples:

orb machines terminate i-1234567890abcdef0
orb machines terminate i-aaa i-bbb --force

machines stop

Stop running machines.

Usage:

orb machines stop [MACHINE_IDS...] [OPTIONS]

Arguments: | Argument | Description | Required | |----------|-------------|----------| | MACHINE_IDS | Machine IDs to stop (positional) | Yes* |

Options: | Flag | Description | Example | |------|-------------|---------| | --force | Force stop without confirmation | --force |

Examples:

orb machines stop i-1234567890abcdef0
orb machines stop i-aaa i-bbb --force

machines start

Start stopped machines.

Usage:

orb machines start [MACHINE_IDS...] [OPTIONS]

Arguments: | Argument | Description | Required | |----------|-------------|----------| | MACHINE_IDS | Machine IDs to start (positional) | Yes* |

Examples:

orb machines start i-1234567890abcdef0
orb machines start i-aaa i-bbb

Requests

Manage provisioning requests.

requests list

List all requests.

Usage:

orb requests list [OPTIONS]

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:

orb requests show REQUEST_ID [OPTIONS]

Arguments: | Argument | Description | Required | |----------|-------------|----------| | REQUEST_ID | Request ID to show (positional) | Yes* |

Options: | Flag | Description | Example | |------|-------------|---------| | --format | Output format | --format yaml |

Examples:

orb requests show req-abc123
orb requests show req-abc123 --format yaml

requests cancel

Cancel a request.

Usage:

orb requests cancel REQUEST_ID [OPTIONS]

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:

orb system status [OPTIONS]

Options: | Flag | Description | Example | |------|-------------|---------| | --format | Output format | --format table |

system health

Run health check.

Usage:

orb system health [OPTIONS]

Options: | Flag | Description | Example | |------|-------------|---------| | --detailed | Show detailed health information | --detailed |

system metrics

Show system metrics.

Usage:

orb system metrics [OPTIONS]

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:

orb server start [OPTIONS]

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.

orb server stop [--timeout N]

server status

Report PID, liveness, and a best-effort /health probe.

orb server status

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).

orb server logs [-n LINES]

Config

Configuration management.

config show

Show configuration.

Usage:

orb config show [OPTIONS]

Options: | Flag | Description | Example | |------|-------------|---------| | --format | Output format | --format yaml |

config set

Set configuration value.

Usage:

orb config set KEY VALUE

Arguments: | Argument | Description | Required | |----------|-------------|----------| | KEY | Configuration key | Yes | | VALUE | Configuration value | Yes |

config get

Get configuration value.

Usage:

orb config get KEY

Arguments: | Argument | Description | Required | |----------|-------------|----------| | KEY | Configuration key | Yes |

config validate

Validate configuration.

Usage:

orb config validate [OPTIONS]

Options: | Flag | Description | Example | |------|-------------|---------| | --file | Configuration file to validate | --file config.json |

Providers

Provider management and operations.

providers list

List available providers.

Usage:

orb providers list [OPTIONS]

Options: | Flag | Description | Example | |------|-------------|---------| | --format | Output format | --format table | | --detailed | Show detailed provider information | --detailed |

providers show

Show provider details.

Usage:

orb providers show [OPTIONS]

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:

orb providers health [OPTIONS]

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:

orb providers add [OPTIONS]

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:

orb providers remove PROVIDER_NAME [OPTIONS]

Arguments: | Argument | Description | Required | |----------|-------------|----------| | PROVIDER_NAME | Provider instance name to remove | Yes |

Examples:

orb providers remove aws-dev

providers update

Update provider configuration.

Usage:

orb providers update PROVIDER_NAME [OPTIONS]

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:

orb providers set-default PROVIDER_NAME

Arguments: | Argument | Description | Required | |----------|-------------|----------| | PROVIDER_NAME | Provider name to set as default | Yes |

Examples:

orb providers set-default aws-prod

providers get-default

Show the current default provider.

Usage:

orb providers get-default [OPTIONS]

Examples:

orb providers get-default
orb providers get-default --format yaml

providers select

Select provider strategy.

Usage:

orb providers select PROVIDER [OPTIONS]

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:

orb providers exec OPERATION [OPTIONS]
orb providers exec --list [--provider-name NAME]

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:

orb providers metrics [OPTIONS]

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_status is 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) or unknown (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_count is the number of live probes run for that provider since the process started.
  • uptime_percent is null. 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:

orb storage list [OPTIONS]

Options: | Flag | Description | Example | |------|-------------|---------| | --format | Output format | --format table |

storage show

Show current storage configuration.

Usage:

orb storage show [OPTIONS]

Options: | Flag | Description | Example | |------|-------------|---------| | --format | Output format | --format yaml | | --strategy | Show specific storage strategy details | --strategy json |

storage validate

Validate storage configuration.

Usage:

orb storage validate [OPTIONS]

Options: | Flag | Description | Example | |------|-------------|---------| | --strategy | Validate specific storage strategy | --strategy json |

storage test

Test storage connectivity.

Usage:

orb storage test [OPTIONS]

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:

orb storage health [OPTIONS]

Options: | Flag | Description | Example | |------|-------------|---------| | --format | Output format | --format table | | --detailed | Show detailed health information | --detailed |

storage metrics

Show storage performance metrics.

Usage:

orb storage metrics [OPTIONS]

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:

orb scheduler list [OPTIONS]

Options: | Flag | Description | Example | |------|-------------|---------| | --format | Output format | --format table | | --long | Show detailed information | --long |

scheduler show

Show scheduler configuration.

Usage:

orb scheduler show [OPTIONS]

Options: | Flag | Description | Example | |------|-------------|---------| | --format | Output format | --format yaml | | --scheduler | Show specific scheduler strategy details | --scheduler hostfactory |

scheduler validate

Validate scheduler configuration.

Usage:

orb scheduler validate [OPTIONS]

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:

orb mcp serve [OPTIONS]

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:

orb mcp validate

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:

orb infrastructure discover [OPTIONS]
orb infra discover [OPTIONS]

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:

orb infrastructure show [OPTIONS]
orb infra show [OPTIONS]

infrastructure validate

Verify that the configured infrastructure still exists in AWS.

Usage:

orb infrastructure validate [OPTIONS]
orb infra validate [OPTIONS]

Init

Initialize ORB configuration.

init

Initialize ORB configuration.

Usage:

orb init [OPTIONS]

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

# Generates templates for ALL active providers
orb templates generate

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 directory
  • ORB_WORK_DIR - Working directory
  • ORB_LOG_DIR - Log directory
  • ORB_LOG_LEVEL - Log level (DEBUG, INFO, WARNING, ERROR)

HostFactory Variables (when using HostFactory scheduler)

  • HF_PROVIDER_CONFDIR - HostFactory config directory
  • HF_PROVIDER_WORKDIR - HostFactory work directory
  • HF_PROVIDER_LOGDIR - HostFactory log directory
  • HF_LOGLEVEL - HostFactory log level
  • HF_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

Development Workflow

# Use different scheduler for testing
orb --scheduler default templates list

# Validate configuration
orb config validate

# Test storage connectivity
orb storage test --timeout 60

# Start API server for development
orb server start --foreground --reload --port 9000