# References Reference
> Auto-generated from docs.expanso.io documentation
## index
# API Reference
The Expanso API provides a REST interface for managing jobs, nodes, and executions across your edge computing infrastructure.
## How It Works
The Expanso API is available on two types of endpoints:
- **Orchestrator**: The central management service for your edge fleet
- **Edge nodes**: Individual edge agents (when running in local mode)
Most API operations work against both endpoint types, with responses varying based on the target. For example, querying the orchestrator returns data across all nodes, while querying an edge node returns data for that specific node only.
### Local Mode
Edge nodes running in "local mode" expose the same API for direct management without an orchestrator connection. This enables:
- Local development and testing workflows
- Direct troubleshooting of specific edge nodes
- Air-gapped or isolated deployments
- Deploying jobs directly to edge nodes
To use the API against an edge node in local mode, point your requests to the edge node's endpoint instead of the orchestrator.
## Base URL
```
https://YOUR_WORKSPACE_ID.us2.cloud.expanso.io:9010/api/v1
```
**Using Your Managed Expanso Cloud Endpoint:**
Each workspace in Managed Expanso Cloud comes with its own orchestrator and a unique endpoint. The examples on this page use the placeholder `YOUR_WORKSPACE_ID`. Replace it with your workspace ID, or copy the full endpoint from:
- Expanso Cloud Console → Your Workspace → Endpoint
Prefer to run the orchestrator in your own environment? A private deployment is available too. Contact the Expanso team at [support@expanso.io](mailto:support@expanso.io) for details and to get set up.
## Authentication
All API requests require authentication. You can use an Expanso Cloud API key:
```bash
curl -H "Authorization: Bearer exp_ak_YOUR_API_KEY" \
https://YOUR_WORKSPACE_ID.us2.cloud.expanso.io:9010/api/v1/jobs
```
Create an API key from the Expanso Cloud dashboard under Settings → API Keys.
## Quick Start
Deploy a job to your edge nodes:
```bash
curl -X PUT \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "log-processor",
"type": "pipeline",
"config": {
"pipeline": {
"inputs": [...],
"processors": [...],
"outputs": [...]
}
},
"selector": {
"match_labels": {
"env": "production"
}
}
}' \
https://YOUR_WORKSPACE_ID.us2.cloud.expanso.io:9010/api/v1/jobs
```
This will deploy the job to all nodes matching the label `env=production`.
## Compare Versions
Compares two historical versions of a job and returns a unified diff.
## When to Use
- Review changes between any two versions before rollback
- Audit historical changes to a job specification
- Debug issues by comparing known-good version with problematic version
## Examples
Compare version 1 to version 3:
`GET /jobs/my-job/versions/diff?from=1&to=3`
Compare version 1 to latest:
`GET /jobs/my-job/versions/diff?from=1`
Request
## Delete Job
Soft-deletes a job and stops all its executions.
## What Happens
1. Job state is set to "deleted"
2. Evaluation is created to stop all active executions
3. Job is excluded from default list views
4. Job data is preserved for audit purposes (versions, history remain accessible)
## When to Use
- Remove a job you no longer need
- Clean up after testing or development
- Decommission jobs for replaced services
- Archive old jobs while preserving audit trail
## State Validation
By default, jobs can only be deleted if they are in a deletable state (stopped, completed, failed).
Use `force: true` to bypass state validation and delete jobs in any state (including running).
## Async Behavior
The API returns immediately after marking the job as deleted. An evaluation is created to
asynchronously stop all executions. Monitor the evaluation to track cleanup progress.
## Common Scenarios
- **Delete completed job**: `DELETE /jobs/my-job` (no force needed)
- **Force delete running job**: `DELETE /jobs/my-job` with `{"force": true}` in body
- **Delete with reason**: `DELETE /jobs/my-job` with `{"reason": "Replaced by v2"}` in body
## Viewing Deleted Jobs
Deleted jobs are soft-deleted. To view: `GET /jobs?states=deleted`
Request
## Delete Node
Soft-deletes a node. The node must be in Lost or Disconnected state unless force is used.
## How It Works
1. **Soft Delete**: Node enters Deleted state immediately, hidden from normal lists
2. **Audit Trail**: Node record preserved with full history
3. **Garbage Collection**: After retention period, GC permanently removes node from database
4. **Execution Cleanup**: GC waits until all node executions are cleaned up before permanent deletion
## State Requirements
- **Lost nodes**: Can be deleted immediately (recommended)
- **Disconnected nodes**: Can be deleted immediately
- **Connected nodes**: Require `force=true` (use with caution)
## Warning: Connected Nodes
Deleting a Connected node with `force=true` should only be used when:
- Node is permanently offline but showing as connected due to stale state
- You're certain the node will not reconnect
- If the node reconnects, it will be re-registered automatically
- Alternatively see what jobs are running on a node: `GET /nodes/{id}/executions`
## Common Patterns
- Decommission lost node: `DELETE /nodes/{id}`
- Remove offline node: `DELETE /nodes/{id}`
- Force delete stuck node: `DELETE /nodes/{id}` with `{"force": true}`
Request
## Describe Job
Returns detailed information about a specific job.
## What is a Job?
A **job** is a unit of work that runs on one or more edge nodes. Jobs define:
- **What to run**: The job type (pipeline, query, etc.) and configuration
- **Where to run**: Node selection criteria (labels, resource requirements)
- **How to run**: Scheduling policy, restart behavior, resource limits
## What You Get
- Complete job specification (name, type, config, selector)
- Current job status (state, version, revision)
- Timestamps (created_at, updated_at)
- Execution count and scheduling information
Request
## Describe Node
Returns detailed information about a specific edge node.
## What You Get
- Node specification (name, hostname, OS, architecture, agent version)
- Current labels and capabilities
- Connection status and session information
- Resource usage metrics (CPU, memory, disk)
- Heartbeat and connectivity timestamps
## When to Use
- Check node health and resource utilization
- Verify node labels before job deployment
- Troubleshoot connectivity issues
- Monitor resource capacity for capacity planning
## Related Endpoints
- `GET /executions?node_ids={id}` - See jobs running on this node
Request
## Expanso API
The Expanso API provides a comprehensive interface for managing distributed computing jobs,
pipelines, and edge nodes across your Expanso deployment.
## Overview
The Expanso API enables you to:
- Manage jobs and pipelines (deploy, update, stop, rerun)
- Track executions and scheduling decisions
- Monitor and manage edge nodes
- Access system health and configuration
## API Structure
All API endpoints are versioned under `/api/v1/` and return JSON responses.
## Error Handling
The API uses standard HTTP status codes and returns detailed error messages in a consistent format.
|
Security Scheme Type:
|
apiKey
|
|
Header parameter name:
|
Authorization
|
Contact
Expanso Support: [support@expanso.io](mailto:support@expanso.io)
URL: [https://expanso.io/contact/](https://expanso.io/contact/)
## Explain Configuration
Returns detailed explanations of all configuration options, their meanings, and current values (credentials redacted).
## Get an execution
Returns detailed information about a specific job execution.
## What You Get
- Execution ID, job ID, node ID, and namespace
- Job version and specification snapshot (spec at execution time)
- Desired state (what the system wants) vs observed state (actual state on node)
- Timestamps (created, updated)
- Details map with execution-specific metadata
## When to Use
- Debug why an execution failed (check observed_state message)
- Verify job version running on a specific node
- Check execution state alignment (desired vs actual)
- Investigate execution lifecycle transitions
## State Tracking
Executions track two states:
- **desired_state**: What the system wants (run, stop)
- **observed_state**: Actual state on the node (pending, running, failed, completed)
Misalignment indicates ongoing transitions or issues.
## Related Endpoints
- `GET /executions/{id}/history` - See state change history for this execution
Request
## Get Configuration
Returns the current configuration of the service, with credential fields redacted.
## Get execution history
Returns state change events and lifecycle history for a specific execution.
WHAT YOU GET:
Timeline of events showing:
- State transitions (pending → starting → running → completed/failed)
- Timestamps for each transition
- Messages explaining why each transition occurred
- System events affecting this execution
WHEN TO USE:
- Debug execution failures (see what led to failed state)
- Investigate slow starts (check time in pending/starting states)
- Audit execution lifecycle for compliance
- Understand execution behavior over time
FILTERING:
- since: Only show events after a specific timestamp (reduces noise)
COMMON PATTERNS:
- "Why did this execution fail?" - Review history for error messages
- "When did this execution start running?" - Find 'running' state transition
- "How long was it pending?" - Calculate time between created and running states
Request
## Get Fleet Statistics
Returns aggregate statistics and metrics across your edge node fleet.
## What You Get
- Total node count and breakdown by connection state
- Aggregate resource usage (total/average CPU, memory, disk)
- Node health distribution (healthy, degraded, unhealthy)
- Fleet-wide capacity metrics
## When to Use
- Monitor overall fleet health at a glance
- Capacity planning and resource forecasting
- Dashboard metrics and alerting
- Trend analysis over time
## Filtering
- `connection_states`: Include only nodes in specific states (connected, disconnected, etc.)
## Use Cases
- "How many nodes are currently connected?" - Check `total_count` with `connection_states=connected`
- "What's my fleet's average resource utilization?" - Review aggregate CPU/memory/disk metrics
- "Do I have capacity for new jobs?" - Compare used vs total resources
Request
## Get Service Status
Returns detailed status information about the service including version, uptime, and statistics.
## Get Version
Returns a specific version of a job.
Request
## List executions for a node
Returns a paginated list of executions running on a specific node.
Request
## List executions
Returns job executions - instances of jobs running on specific nodes.
## What are Executions?
When a job is assigned to a node, an execution is created. Each execution:
- Represents one job running on one specific node
- Has its own lifecycle (pending → starting → running → completed/failed/stopped)
- Tracks both desired state (what the system wants) and observed state (actual node state)
- Can be monitored and managed independently
## Filtering
- `job_id`: Show executions for a specific job
- `node_ids`: Show executions on specific nodes
- `states`: Filter by execution state (running, failed, completed, etc.)
- `namespace`: Filter by namespace (if multi-tenant)
## Common Workflows
- See where a job is running: `?job_id=job-abc123`
- Monitor execution health: `?states=failed,lost`
- Check specific node's workload: `?node_ids=node-123`
- Track job version rollout: Filter by job and check job_version field
## Relationship to Jobs
One job can have many executions (one per matching node). To see executions
for a specific job, use `GET /jobs/{id}/executions` instead.
## Related Endpoints
- `GET /jobs/{id}/executions` - Executions for a specific job
- `GET /executions?node_ids={id}` - Executions on a specific node
- `GET /executions/{id}` - Details about one execution
Request
## List Jobs
Returns a paginated list of jobs with optional filtering and sorting.
## Filtering
Filter jobs using query parameters:
- `types`: Filter by job type (pipeline, query, update, config)
- `states`: Filter by job state (pending, running, stopped, etc.)
- `labels`: Label selector for matching jobs (e.g., "env=prod,region=us-west")
- `namespace`: Filter by namespace (if multi-tenant)
## Pagination
1. First request: Specify `limit` (default 50, max 1000)
2. Response includes `next_token` if more results available
3. Subsequent requests: Include `next_token` from previous response
4. Continue until `next_token` is empty
## Sorting
- `order_by`: Field to sort by (created_at, updated_at, name)
- `order`: Sort direction (asc or desc)
- Default: created_at desc (newest first)
## Common Patterns
- All running jobs: `?states=running`
- Production pipelines: `?types=pipeline&labels=env=production`
- Recently updated: `?order_by=updated_at&order=desc&limit=10`
Request
## List Nodes
Returns edge nodes with filtering and pagination.
## What are Nodes?
Nodes are edge agents that execute jobs. Each node has:
- Labels for selection (env, region, capabilities, hardware specs)
- Resource information (CPU, memory, disk usage and capacity)
- Connection state (connected, disconnected, initializing)
- Capabilities (supported inputs, outputs, processors, runtimes)
## Filtering
- `states`: Filter by node health (healthy, degraded, unhealthy)
- `labels`: Label selector for matching nodes (e.g., "env=prod,region=us-west")
## Common Patterns
- Find nodes for job placement: Filter by labels matching your job selector
- Monitor node health: `?states=degraded,unhealthy`
- Find nodes by region: `?labels=region=us-west`
- List all connected nodes: (default - shows healthy nodes)
- Recently registered: `?order_by=created_at&order=desc&limit=10`
## Related Endpoints
- `GET /executions?node_ids={id}` - See what jobs are running on a specific node
- `GET /nodes/-/stats` - Get aggregate statistics across all nodes
Request
## List Versions
Returns all versions for a specific job.
Request
## Liveness/readiness probe
Unauthenticated minimal health probe for Kubernetes liveness/readiness checks.
Returns only overall status and a timestamp. For version, uptime, build info,
or per-component details use the authenticated /status endpoint.
## Live log stream WebSocket
Upgrades to a WebSocket that streams live logs from one edge node running the job.
The orchestrator validates auth, resolves the target edge node, and proxies
the Loki tail stream back to the client. Opening the WS signals the orchestrator
to start tailing; closing the WS signals it to stop.
If `node_id` is omitted, the orchestrator picks one node randomly from the job's
active executions; logs from other executions of the same job are not included.
Request
## Pause Rollout
Pauses the active rollout for a job. The current wave will complete,
but no new waves will start until the rollout is resumed.
Request
## Preview Changes
Compares a proposed job specification with an existing job to preview changes.
## When to Use:
- Before deploying job updates: Preview exactly what will change
- Validate changes: Ensure updates match your intentions
- Code review: Share diffs with team before deploying
- Troubleshooting: Verify a job spec matches what you expect
## What You Get
- Unified diff showing additions, removals, and changes
- Line-by-line comparison of the job specifications
- Empty diff if specs are identical (no changes)
## Common Workflow
1. Modify your job specification file
2. `PUT /jobs/diff` with the new spec
3. Review the diff to verify changes
4. If changes look correct: `PUT /jobs` to apply
5. If not: Adjust spec and repeat
## Important Notes
- This is read-only - it doesn't modify the job
- Internal metadata (expanso.io/* keys) are ignored in diff
- Empty diff means no changes will be applied (422 on PUT /jobs)
Request
## Update Job by ID
Updates an existing job by its ID, allowing full updates including name changes.
## Difference from PUT /jobs
- **PUT /jobs**: Name-based upsert (creates if doesn't exist, updates if exists)
- **PUT /jobs/:id**: ID-based update (job must exist, allows renaming)
## When to Use
- **Rename a job**: Change the job name while preserving ID and history
- **Explicit updates**: Target a specific job instance by ID
- **Avoid name collisions**: Update without worrying about name-based lookup
## What Happens
1. API looks up job by ID (404 if not found)
2. Validates name uniqueness if name changed (409 if conflict)
3. Updates job specification
4. Preserves job ID, history, and version information
5. Creates evaluation to reschedule with new spec
## Error Responses
- **400 Bad Request**: Invalid job specification
- **404 Not Found**: Job with specified ID doesn't exist
- **409 Conflict**: New job name already exists in namespace
- **422 Unprocessable Entity**: No changes detected (spec unchanged)
- **500 Internal Server Error**: Server-side storage or processing error
Request
## Deploy Job
Deploys a new job or updates an existing one.
A **job** is a unit of work that runs on edge nodes (pipelines, queries, services).
This endpoint creates or updates job specifications.
## What Happens
1. API validates job specification (syntax, required fields, selector)
2. Job is stored in the state store
3. API returns immediately after successful storage
4. An evaluation is created asynchronously
5. Scheduler matches job to nodes based on selector
6. Executions are created on matching nodes
## When to Use
- **Initial deployment**: Creates new job (returns 201 Created)
- **Updates**: Modifies existing job spec (returns 200 OK)
- Job spec changes trigger re-evaluation and updates to executions
## Async Behavior
This endpoint returns after validation and storage, NOT after node assignment.
- Use `GET /jobs/{id}/executions` to check where the job is running
- Use `GET /jobs/{id}/history` to see scheduling history
## Error Responses
- **400 Bad Request**: Invalid job specification (check syntax, required fields)
- **422 Unprocessable Entity**: Valid format but no changes detected (spec unchanged from current version)
- **500 Internal Server Error**: Server-side storage or processing error
Request
## Rerun Job
Triggers a new scheduler evaluation without changing the job specification.
## What Rerun Means
Rerun creates a new evaluation to force the scheduler to reassess the job.
This is different from updating a job (`PUT /jobs`):
- **Rerun**: Job spec stays the same, scheduler re-evaluates
- **Update**: Job spec changes, triggers new evaluation
## When to Use
- Job failed to schedule: Force re-evaluation after fixing node issues
- Nodes changed: New nodes added or labels updated since last deployment
- Stuck evaluation: Evaluation is blocked or pending for too long
- Manual retry: After resolving external issues (network, resources, etc.)
## What Happens
1. Creates a new evaluation for the job (with current spec)
2. Scheduler re-analyzes node matching and placement
3. Creates/updates/stops executions as needed
4. Returns immediately (async operation)
## When NOT to Use
- To change job configuration: Use `PUT /jobs/{id}` instead
- To stop a job: Use `POST /jobs/{id}/stop` instead
- If job is already running correctly: Rerun is unnecessary
## Common Scenarios
- "Job shows 'blocked - no nodes match selector'" → Added matching nodes → Rerun
- "Updated node labels" → Rerun jobs that target those labels
- "Network issue resolved" → Rerun jobs that failed to deploy
Request
## Resume Rollout
Resumes a paused rollout for a job, continuing from where it left off.
Request
## Rollback Job
Rolls back a job to a previous version. This atomically:
- Updates the job spec to the target version's spec
- Cancels any active deployment
- Creates a new rollback deployment with immediate strategy
Request
## api.ComponentMetrics
api.ComponentMetrics API schema defining 7 fields, including component name, errors, latency, and 4 more.
## api.CPUStats
api.CPUStats API schema defining 3 fields, including avg percent, max percent, and min percent.
## api.DeleteJobRequest
api.DeleteJobRequest API schema defining 3 fields, including force, namespace, and reason.
## api.DeleteJobResponse
api.DeleteJobResponse API schema defining 1 field, including job id.
## api.DeleteNodeRequest
api.DeleteNodeRequest API schema defining 2 fields, including force and reason.
## api.DeleteNodeResponse
api.DeleteNodeResponse API schema defining 2 fields, including message and node id.
## api.DiskStats
api.DiskStats API schema defining 5 fields, including avg percent, capacity bytes, max percent, and 2 more.
## api.GetExecutionHistoryResponse
api.GetExecutionHistoryResponse API schema defining 2 fields, including items and next token.
## api.GetExecutionResponse
api.GetExecutionResponse API schema defining 1 field, including execution.
## api.GetJobDiffRequest
api.GetJobDiffRequest API schema defining 1 field, including spec.
## api.GetJobDiffResponse
api.GetJobDiffResponse API schema defining 2 fields, including Diff and Warnings.
## api.GetJobHistoryResponse
api.GetJobHistoryResponse API schema defining 2 fields, including items and next token.
## api.GetJobResponse
api.GetJobResponse API schema defining 1 field, including job.
## api.GetJobVersionResponse
api.GetJobVersionResponse API schema defining 1 field, including version.
## api.GetNodeResponse
api.GetNodeResponse API schema defining 1 field, including node.
## api.GetNodeStatsResponse
api.GetNodeStatsResponse API schema defining 5 fields, including nodes by arch, nodes by connection state, nodes by os, and 2 more.
## api.GetVersionsDiffResponse
api.GetVersionsDiffResponse API schema defining 4 fields, including diff, from version, job id, and 1 more.
## api.Histogram
api.Histogram API schema defining 4 fields, including bounds, bucket counts, count, and 1 more.
## api.ListExecutionsResponse
api.ListExecutionsResponse API schema defining 2 fields, including items and next token.
## api.ListJobExecutionsResponse
api.ListJobExecutionsResponse API schema defining 2 fields, including items and next token.
## api.ListJobsResponse
api.ListJobsResponse API schema defining 2 fields, including items and next token.
## api.ListJobVersionsResponse
api.ListJobVersionsResponse API schema defining 2 fields, including items and next token.
## api.ListNodeExecutionsResponse
api.ListNodeExecutionsResponse API schema defining 2 fields, including items and next token.
## api.ListNodesResponse
api.ListNodesResponse API schema defining 2 fields, including items and next token.
## api.MemoryStats
api.MemoryStats API schema defining 5 fields, including avg percent, capacity bytes, max percent, and 2 more.
## api.NodePipelineMetricsSnapshot
api.NodePipelineMetricsSnapshot API schema defining 2 fields, including connection state and pipelines.
## api.NodeResourceMetricsSnapshot
api.NodeResourceMetricsSnapshot API schema defining 2 fields, including connection state and samples.
## api.PauseRolloutRequest
api.PauseRolloutRequest API schema defining 3 fields, including dry run, namespace, and reason.
## api.PauseRolloutResponse
api.PauseRolloutResponse API schema defining 1 field, including job id.
## api.PipelineMetricSample
api.PipelineMetricSample API schema defining 8 fields, including bytes input, bytes output, components, and 5 more.
## api.PipelineMetricsSnapshot
api.PipelineMetricsSnapshot API schema defining 3 fields, including connection state, pipeline id, and samples.
## api.PutJobRequest
api.PutJobRequest API schema defining 3 fields, including dry run, force, and spec.
## api.PutJobResponse
api.PutJobResponse API schema defining 3 fields, including created, job, and warnings.
## api.RerunJobRequest
api.RerunJobRequest API schema defining 1 field, including namespace.
## api.RerunJobResponse
api.RerunJobResponse API schema defining 3 fields, including job id, version, and warnings.
## api.ResourceMetricSample
api.ResourceMetricSample API schema defining 9 fields, including cpu percent, disk capacity bytes, disk percent, and 6 more.
## api.ResourceStats
api.ResourceStats API schema defining 3 fields, including cpu, disk, and memory.
## api.ResumeRolloutRequest
api.ResumeRolloutRequest API schema defining 3 fields, including dry run, namespace, and reason.
## api.ResumeRolloutResponse
api.ResumeRolloutResponse API schema defining 1 field, including job id.
## api.RollbackJobRequest
api.RollbackJobRequest API schema defining 4 fields, including dry run, namespace, reason, and 1 more.
## api.RollbackJobResponse
api.RollbackJobResponse API schema defining 5 fields, including job id, rollback to version, target spec, and 2 more.
## api.StopJobRequest
api.StopJobRequest API schema defining 2 fields, including namespace and reason.
## api.StopJobResponse
api.StopJobResponse API schema defining 1 field, including job id.
## errors.Error
errors.Error API schema defining 7 fields, including code, component, details, and 4 more.
## errors.ErrorCode
errors.ErrorCode API schema defining 40 allowed values.
## types.BuildInfo
types.BuildInfo API schema defining 4 fields, including commit, date, go version, and 1 more.
## types.ConfigExplainResponse
types.ConfigExplainResponse API schema defining 1 field, including sources.
## types.ConfigSource
types.ConfigSource API schema defining 3 fields, including key, source, and value.
## types.ConnectionHealth
types.ConnectionHealth API schema defining 8 fields, including connected since, consecutive failures, handshake required, and 5 more.
## types.ConnectionState
types.ConnectionState API schema defining 3 allowed values.
## types.ConnectionStatus
types.ConnectionStatus API schema defining 2 fields, including health and url.
## types.Duration
types.Duration API schema defining 11 allowed values.
## types.EnrollmentSourceType
types.EnrollmentSourceType API schema defining 9 allowed values.
## types.EvaluationsSummary
types.EvaluationsSummary API schema defining 4 fields, including inflight, pending, ready, and 1 more.
## types.Execution
types.Execution API schema defining 10 fields, including eval id, id, job id, and 7 more.
## types.ExecutionDesiredState
types.ExecutionDesiredState API schema defining 3 allowed values.
## types.ExecutionsSummary
types.ExecutionsSummary API schema defining 2 fields, including by state and total.
## types.ExecutionStateType
types.ExecutionStateType API schema defining 10 allowed values.
## types.ExecutionStatus
types.ExecutionStatus API schema defining 9 fields, including created at, desired state, details, and 6 more.
## types.HealthCheckConfig
types.HealthCheckConfig API schema defining 5 fields, including deadline, failure threshold, interval, and 2 more.
## types.HealthResponse
types.HealthResponse API schema defining 2 fields, including status and timestamp.
## types.HealthStatusType
types.HealthStatusType API schema defining 3 allowed values.
## types.HistoryEvent
types.HistoryEvent API schema defining 7 fields, including details, execution id, job id, and 4 more.
## types.Identity
types.Identity API schema defining 4 fields, including name, network id, node id, and 1 more.
## types.Job
types.Job API schema defining 3 fields, including id, spec, and status.
## types.JobSpec
types.JobSpec API schema defining 14 fields, including config, description, labels, and 11 more.
## types.JobsSummary
types.JobsSummary API schema defining 3 fields, including by state, latest created at, and total.
## types.JobStateType
types.JobStateType API schema defining 12 allowed values.
## types.JobStatus
types.JobStatus API schema defining 6 fields, including created at, revision, rollout, and 3 more.
## types.JobVersion
types.JobVersion API schema defining 4 fields, including id, spec, status, and 1 more.
## types.Node
types.Node API schema defining 4 fields, including id, identity, spec, and 1 more.
## types.NodeCapabilities
types.NodeCapabilities API schema defining 4 fields, including inputs, outputs, processors, and 1 more.
## types.NodeConnectionState
types.NodeConnectionState API schema defining 5 allowed values.
## types.NodeIdentity
types.NodeIdentity API schema defining 14 fields, including cert serial, credential valid until, enrolled at, and 11 more.
## types.NodeIdentityStatus
types.NodeIdentityStatus API schema defining 3 allowed values.
## types.NodeSchedulingEligibility
types.NodeSchedulingEligibility API schema defining 2 allowed values.
## types.NodeSelector
types.NodeSelector API schema defining 3 fields, including match expressions, match ids, and match labels.
## types.NodeSpec
types.NodeSpec API schema defining 8 fields, including agent version, arch, capabilities, and 5 more.
## types.NodesSummary
types.NodesSummary API schema defining 3 fields, including by connection, latest join time, and total.
## types.NodeStatus
types.NodeStatus API schema defining 11 fields, including connected since, connection state, created at, and 8 more.
## types.ProcessResourceUsage
types.ProcessResourceUsage API schema defining 2 fields, including cpu utilization and memory used bytes.
## types.ResourceInfo
types.ResourceInfo API schema defining 4 fields, including cpu percent, disk percent, goroutines, and 1 more.
## types.ResourceUsage
types.ResourceUsage API schema defining 7 fields, including cpu percent, disk capacity bytes, disk percent, and 4 more.
## types.RolloutSpec
types.RolloutSpec API schema defining 9 fields, including auto promote, canary count, canary percent, and 6 more.
## types.RolloutStatus
types.RolloutStatus API schema defining 11 fields, including canary nodes, canary promoted, completed at, and 8 more.
## types.RolloutStrategyType
types.RolloutStrategyType API schema defining 3 allowed values.
## types.RolloutType
types.RolloutType API schema defining 4 allowed values.
## types.RuntimeInfo
types.RuntimeInfo API schema defining 5 fields, including build, start time, status, and 2 more.
## types.SecretAuthConfig
types.SecretAuthConfig API schema defining 24 fields, including access key id, client id, client secret env, and 21 more.
## types.SecretProviderSpec
types.SecretProviderSpec API schema defining 15 fields, including address, auth, duration seconds, and 12 more.
## types.SecretSpec
types.SecretSpec API schema defining 16 fields, including encoding, engine version, field, and 13 more.
## types.State-types_ExecutionDesiredState
types.State-types_ExecutionDesiredState API schema defining 3 fields, including details, message, and state type.
## types.State-types_ExecutionStateType
types.State-types_ExecutionStateType API schema defining 3 fields, including details, message, and state type.
## types.State-types_JobStateType
types.State-types_JobStateType API schema defining 3 fields, including details, message, and state type.
## types.StatusResponse
types.StatusResponse API schema defining 10 fields, including collected at, connection, evaluations, and 7 more.
## types.StoreStatus
types.StoreStatus API schema defining 2 fields, including db size bytes and entities.
## types.TimeoutConfig
types.TimeoutConfig API schema defining 3 fields, including execution timeout, queue timeout, and total timeout.
## types.TLSConfig
types.TLSConfig API schema defining 4 fields, including ca cert, client cert, client key, and 1 more.
## Show History
Returns history events for a specific job.
Request
## Snapshot all pipeline metrics for a node
Returns the retained metric window for each pipeline with data on a node, plus the node connection state.
Request
## Snapshot node resource metrics
Returns the retained resource-usage window (CPU/memory/disk from heartbeats) for a node, plus the node connection state.
Request
## Snapshot pipeline metrics
Returns the retained curated-metric window for one pipeline on one node, plus the node connection state.
Request
## Stop Job
Stops a running job and all its executions.
Request
## Stream node resource metrics (history + live)
SSE: a history event, then a sample event per heartbeat, and a status event on connection-state change.
Payloads by event: history=api.NodeResourceMetricsSnapshot, sample=api.ResourceMetricSample,
status=api.NodeResourceMetricsStatus.
Request
## Stream pipeline metrics (history + live)
SSE: a history event, then a sample event per live batch, and a status event on connection-state change.
Payloads by event: history=api.PipelineMetricsSnapshot, sample=api.PipelineMetricSample, status=api.PipelineMetricsStatus.
Request
## Build Provenance
# Build Provenance
Every publicly distributed Expanso CLI and Expanso Edge artifact — container images and binaries — ships with signed **build provenance**: a [SLSA](https://slsa.dev/spec/v1.0/) attestation recording which source commit, workflow, and build run produced that exact file.
Anyone can verify it. You do not need an Expanso account, a GitHub login, or access to Expanso's source repository.
A checksum tells you a file matches the value you were given. Provenance tells you **where the file came from**: that this exact byte sequence was produced by Expanso's release pipeline, from a named commit, in a build run you can point at — and not rebuilt, patched, or substituted by anyone in between.
## What's covered
| Artifact | Distributed via | Where the provenance lives |
|---|---|---|
| Container images (Expanso CLI, Expanso Edge) | `ghcr.io/expanso-io/expanso-cli`, `ghcr.io/expanso-io/expanso-edge` | In the registry, next to the image |
| Binaries, every OS and architecture (Expanso CLI, Expanso Edge) | `get.expanso.io` | A `*_provenance.intoto.jsonl` bundle next to the tarballs |
:::note[Which releases carry provenance]
Provenance is attached to release artifacts built **after 12 August 2026**, and artifacts built from **14 August 2026** onward come from the hardened pipeline described under [what verification proves](#what-verification-does-and-doesnt-prove). Anything published before that — including stable `v2.1.20` — has no attestation, and there is no bundle to download. Nightly builds carry provenance now; stable releases do from the next stable release onward.
:::
## Verification policy
Verifying a signature only tells you *something* signed the artifact. What makes provenance meaningful is checking **which identity** signed it. Enforce all four of these:
| Property | Required value |
|---|---|
| Predicate type | `https://slsa.dev/provenance/v1` |
| Repository owner | `https://github.com/expanso-io` |
| OIDC issuer | `https://token.actions.githubusercontent.com` |
| Signer workflow — **images** | `expanso-io/expanso/.github/workflows/_docker-release.yml` |
| Signer workflow — **binaries** | `expanso-io/expanso/.github/workflows/_release.yml` |
:::caution[Always pin the signer workflow]
`--owner expanso-io` on its own accepts an attestation signed by *any* workflow in the organization. Adding `--signer-workflow` restricts it to the release pipeline, which is what makes the provenance non-forgeable by other build jobs. The commands below always pass it.
:::
## Before you start
You need the [GitHub CLI](https://cli.github.com/) (`gh` 2.x) for `gh attestation verify`, plus `curl` and `jq`. **You do not need to run `gh auth login`** — every command below reads a locally downloaded bundle and talks only to the public Sigstore trust root.
## Verify a binary
Binaries publish their provenance bundle alongside the tarballs. Download both, then verify:
```bash
MODULE=edge # or: cli
CHANNEL=nightly # or: stable
BINARY=expanso-edge # or: expanso-cli
# Look up the current version for that module and channel
VERSION=$(curl -s "https://get.expanso.io/manifests/$MODULE/$CHANNEL.json" | jq -r .version)
BASE="https://get.expanso.io/releases/$MODULE/$CHANNEL/$VERSION"
curl -sSLO "$BASE/${BINARY}_${VERSION}_linux_amd64.tar.gz"
curl -sSLO "$BASE/${BINARY}_${VERSION}_provenance.intoto.jsonl"
gh attestation verify "${BINARY}_${VERSION}_linux_amd64.tar.gz" \
--bundle "${BINARY}_${VERSION}_provenance.intoto.jsonl" \
--owner expanso-io \
--signer-workflow expanso-io/expanso/.github/workflows/_release.yml
```
A successful verification prints the policy it enforced and the attestation that satisfied it:
```
Loaded digest sha256:c3f982813ec95e0332b0bc5bbe1ad7e76cb9b41d4ed78597530b3910651ac7fc for file://expanso-edge_v2.1.21-nightly.36.gc0bf2c76_linux_amd64.tar.gz
Loaded 1 attestations from expanso-edge_v2.1.21-nightly.36.gc0bf2c76_provenance.intoto.jsonl
The following policy criteria will be enforced:
- Predicate type must match:................ https://slsa.dev/provenance/v1
- Source Repository Owner URI must match:... https://github.com/expanso-io
- Subject Alternative Name must match regex: ^https://github.com/expanso-io/expanso/.github/workflows/_release.yml
- OIDC Issuer must match:................... https://token.actions.githubusercontent.com
✓ Verification succeeded!
The following 1 attestation matched the policy criteria
```
The command exits `0` on success and non-zero on any failure, so it drops straight into a script or an installer.
:::tip[One bundle covers every platform]
A module's bundle lists all of its OS/architecture tarballs as subjects, so the same `.intoto.jsonl` verifies the `darwin_arm64` download as well as the `linux_amd64` one. Download it once.
:::
### Cross-check the checksum
The release manifest carries a SHA-256 for every artifact, which should match the digest `gh` computed above:
```bash
curl -s "$BASE/manifest.json" | jq -r '.artifacts.linux_amd64.sha256'
# c3f982813ec95e0332b0bc5bbe1ad7e76cb9b41d4ed78597530b3910651ac7fc
```
## Verify a container image
Image provenance is stored in the registry itself, so it is fetchable anonymously. Pull the bundle, then verify the image by digest:
```bash
REPO=expanso-io/expanso-edge # or: expanso-io/expanso-cli
TAG=nightly
REG="https://ghcr.io/v2/$REPO"
TOKEN=$(curl -s "https://ghcr.io/token?scope=repository:$REPO:pull&service=ghcr.io" | jq -r .token)
AUTH="Authorization: Bearer $TOKEN"
IDX='Accept: application/vnd.oci.image.index.v1+json'
MAN='Accept: application/vnd.oci.image.manifest.v1+json'
# Resolve the tag to an immutable digest
DIGEST=$(curl -sI -H "$AUTH" -H "$IDX" "$REG/manifests/$TAG" \
| tr -d '\r' | grep -i '^docker-content-digest:' | awk '{print $2}')
# The attestation is published under the OCI referrers fallback tag: sha256-
ATT=$(curl -s -H "$AUTH" -H "$IDX" "$REG/manifests/${DIGEST/:/-}" | jq -r '.manifests[0].digest')
BLOB=$(curl -s -H "$AUTH" -H "$MAN" "$REG/manifests/$ATT" | jq -r '.layers[0].digest')
curl -sL -H "$AUTH" "$REG/blobs/$BLOB" > image-provenance.json
gh attestation verify "oci://ghcr.io/$REPO@$DIGEST" \
--bundle image-provenance.json \
--owner expanso-io \
--signer-workflow expanso-io/expanso/.github/workflows/_docker-release.yml
```
```
Loaded 1 attestations from image-provenance.json
The following policy criteria will be enforced:
- Predicate type must match:................ https://slsa.dev/provenance/v1
- Source Repository Owner URI must match:... https://github.com/expanso-io
- Subject Alternative Name must match regex: ^https://github.com/expanso-io/expanso/.github/workflows/_docker-release.yml
- OIDC Issuer must match:................... https://token.actions.githubusercontent.com
✓ Verification succeeded!
The following 1 attestation matched the policy criteria
```
Always verify by **digest**, not by tag. Tags like `nightly` and `latest` move; a digest names one immutable image.
:::note[Why the manual bundle fetch]
Registry-native tools normally discover attestations through the [OCI referrers API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers). GHCR does not currently serve referrers for these packages, so the recipe above reads the fallback tag (`sha256-`) that the attestation is published under instead. The bundle it returns is a standard Sigstore bundle.
:::
## Verifying without access to the source repository
`gh attestation verify` can also look attestations up online, by passing `--owner` without `--bundle`. That queries GitHub's attestation store for the source repository — which is private, so anyone outside the organization gets:
```
Error: HTTP 401: Bad credentials (https://api.github.com/orgs/expanso-io/attestations/sha256:d67cc76c...)
```
This is expected, and it is why every command on this page passes `--bundle`. The published bundles are self-contained: each one carries the signed statement and the certificate chain, so verification runs against the public Sigstore trust root and needs no GitHub credentials and no source access. If you see the error above, you used the online lookup by mistake.
## Read the provenance yourself
The bundle is a JSON document you can inspect without any verification tooling. Its DSSE payload is a base64-encoded [in-toto](https://in-toto.io/) statement:
```bash
jq -r '.dsseEnvelope.payload' image-provenance.json | base64 -d | jq .
```
The interesting fields, from a real nightly image build:
```json
{
"predicate": {
"buildDefinition": {
"buildType": "https://actions.github.io/buildtypes/workflow/v1",
"externalParameters": {
"workflow": {
"ref": "refs/heads/main",
"repository": "https://github.com/expanso-io/expanso",
"path": ".github/workflows/nightly-release.yml"
}
},
"resolvedDependencies": [
{
"uri": "git+https://github.com/expanso-io/expanso@refs/heads/main",
"digest": {"gitCommit": "c0bf2c764f8b37832d20f97f19284e45ce2e0c41"}
}
]
},
"runDetails": {
"builder": {"id": "https://github.com/expanso-io/expanso/.github/workflows/_docker-release.yml@refs/heads/main"},
"metadata": {"invocationId": "https://github.com/expanso-io/expanso/actions/runs/31786485060/attempts/1"}
}
}
}
```
Reading that: the artifact was built from commit `c0bf2c76` on `main` by the release pipeline, and `builder.id` is the workflow whose signing identity you pinned. The `invocationId` links to the build run.
The `gitCommit` is the value to quote in an audit record, and it's the same commit the binary reports at runtime — so you can tie a running node back to a verified build:
```console
$ expanso-edge version --detailed
Version: v2.1.21-nightly.36.gc0bf2c76
Git Commit: c0bf2c764f8b37832d20f97f19284e45ce2e0c41
Build Date: 2026-08-14T09:01:30Z
```
### Signing certificate details
Verification checks the signing certificate for you, but if you're auditing by hand it also records which commit of the *workflow* did the signing, separately from the source commit:
```bash
jq -r '.verificationMaterial.certificate.rawBytes' image-provenance.json \
| base64 -d | openssl x509 -inform DER -noout -text
```
| Certificate extension | OID | Meaning |
|---|---|---|
| Build Config URI / Digest | `…57264.1.18` / `.19` | The entry workflow that was triggered, and the commit it was read at |
| Build Signer URI / Digest | `…57264.1.9` / `.10` | The reusable workflow that minted the attestation, and its commit |
| Source Repository Digest | `…57264.1.13` | The commit the artifact was built from |
All three digests hold the same commit for Expanso releases, because the entry workflow calls the signing workflow by local path (`./.github/workflows/…`), which GitHub always resolves at the caller's commit. They would only diverge if the signing workflow were pulled from another repository or pinned to a different ref.
## Air-gapped verification
Verification normally fetches the Sigstore trust root over the network. Capture it once while online, then verify offline:
```bash
gh attestation trusted-root > trusted_root.jsonl # run once, while online
gh attestation verify "${BINARY}_${VERSION}_linux_amd64.tar.gz" \
--bundle "${BINARY}_${VERSION}_provenance.intoto.jsonl" \
--custom-trusted-root trusted_root.jsonl \
--owner expanso-io \
--signer-workflow expanso-io/expanso/.github/workflows/_release.yml
```
## What verification does and doesn't prove
A successful verification tells you:
- The artifact was produced by Expanso's release pipeline, on GitHub-hosted infrastructure, from the source commit named in the provenance.
- It has not been altered since that build — any change to a single byte fails the check.
- The signing identity belongs to the release workflow, not to the code being built. From 14 August 2026 the identity is issued only to dedicated attestation jobs that run no build code, so a compromised build step cannot mint provenance in the release pipeline's name — the isolation [SLSA Build Level 2](https://slsa.dev/spec/v1.0/levels#build-l2) asks for.
It does not tell you:
- That the source code is free of defects or vulnerabilities. Provenance is about origin, not quality — pair it with your own scanning.
- Anything about an artifact you didn't verify. Verify the specific digest you are about to deploy, not a tag you resolved earlier.
- Anything about locally built binaries. Only artifacts built by the release pipeline are attested; a binary you built yourself has no provenance.
## Next steps
- **[Installation](/getting-started/installation)** - Download and install the CLI and edge agent
- **[Platform Support](/references/platform-support)** - Supported operating systems and architectures
## index
# CLI Reference
Expanso provides command-line tools for managing your edge computing infrastructure.
## Available CLIs
- [expanso-cli](./expanso-cli/index.md) - Command-line interface for interacting with Expanso
- [expanso-edge](./expanso-edge/index.md) - Edge agent command-line tool
## Installation
For installation instructions, see the [Getting Started - Installation](/getting-started/installation) guide.
## How It Works
The Expanso CLI works against Expanso endpoints, which can be either:
- **Control plane**: The central management service (hosted in Expanso Cloud or your infrastructure)
- **Edge nodes**: Individual edge agents running on your devices
Your configured profile endpoint determines what you're talking to. Most operations work against both types of endpoints, with output varying based on the target.
### Local Mode
Edge nodes can run in "local mode" for standalone operation without an orchestrator connection. This is useful for:
- Local development and testing
- Troubleshooting specific edge nodes
- Air-gapped or isolated deployments
When an edge node runs in local mode, you can deploy jobs directly to it using the CLI by pointing your profile to the edge node's endpoint.
## Getting Started
```bash
# Configure your profile to point to your workspace's orchestrator
# (endpoint: Expanso Cloud Console → Your Workspace → Endpoint)
expanso-cli profile save production --endpoint https://YOUR_WORKSPACE_ID.us2.cloud.expanso.io:9010 --select
# Check status
expanso-cli status
# List your nodes
expanso-cli node list
```
## Expanso CLI
## `expanso-cli`
Expanso CLI - Command-line interface for Expanso
### Synopsis
Expanso CLI is the command-line interface for interacting with Expanso.
#### Key Concepts:
• Profiles: Connection configurations for different Expanso environments
• Jobs: Specifications for data processing pipelines that run on edge nodes
• Nodes: Edge agents connected to the control plane
• Evaluations: Scheduler decisions about job assignment to nodes
• Executions: Job instances running on specific nodes
#### Getting Started:
1. Save a profile to connect to the control plane:
expanso-cli profile save prod --endpoint api.expanso.io --api-key exp_ak_YOUR_KEY --select
2. List available edge nodes:
expanso-cli node list
3. Deploy a job:
expanso-cli job deploy log-processor.yaml
4. Check job status:
expanso-cli job describe log-processor
5. View executions on nodes:
expanso-cli execution list --job log-processor
For shell completion setup, run 'expanso-cli completion --help'
#### Environment:
EXPANSO_CLI_AUTH_API_KEY API key for authentication (exp_ak_...) (same as --api-key)
EXPANSO_CLI_CONFIG_DIR Base dir for CLI config/profiles (default ~/.expanso/cli-client)
EXPANSO_CLI_DESCRIPTION Profile description (same as --description)
EXPANSO_CLI_ENDPOINT API endpoint URL (same as --endpoint)
EXPANSO_CLI_PROFILE Profile to use (same as --profile)
EXPANSO_CLI_TIMEOUT Request timeout, e.g. 30s (same as --timeout)
EXPANSO_CLI_TLS_INSECURE Skip TLS certificate verification (dev only) (same as --insecure)
Prefer these over the equivalent flags for secrets: flag values are
visible in `ps` output and in /proc/``/cmdline on Linux.
### Options
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-h, --help help for expanso-cli
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli completion](completion/) - Generate shell completion scripts
* [expanso-cli config](config/) - Configuration management commands
* [expanso-cli execution](execution/) - Manage executions
* [expanso-cli health](health/) - Check health
* [expanso-cli job](job/) - Manage jobs
* [expanso-cli node](node/) - Manage nodes
* [expanso-cli profile](profile/) - Manage client connection profiles
* [expanso-cli status](status/) - Get status
* [expanso-cli version](version/) - Print version information
## Completion
## `expanso-cli completion`
Generate shell completion scripts
### Synopsis
Generate shell completion scripts for expanso-cli commands.
After setup, press TAB to autocomplete resource IDs, names, and commands.
Tab completion works for job names/IDs, node names/IDs, and other resources.
#### Bash:
# Create directory if it doesn't exist
mkdir -p ~/.local/share/bash-completion/completions
# Generate and save completion script
expanso-cli completion bash > ~/.local/share/bash-completion/completions/expanso-cli
# Reload your shell
source ~/.bashrc
#### Zsh:
Option 1 - System-wide (recommended, requires sudo):
# Create directory if it doesn't exist
sudo mkdir -p /usr/local/share/zsh/site-functions
# Install completion
expanso-cli completion zsh | sudo tee /usr/local/share/zsh/site-functions/_expanso-cli
# Restart shell
exec zsh
Option 2 - User-level (no sudo):
# Create user completion directory
mkdir -p ~/.zsh/completions
# Generate completion file
expanso-cli completion zsh > ~/.zsh/completions/_expanso-cli
# Add to ~/.zshrc (only needed once):
echo '`fpath=(~/.zsh/completions $fpath)`' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
# Restart shell
exec zsh
#### Fish:
# Create directory if it doesn't exist
mkdir -p ~/.config/fish/completions
# Generate completion file
expanso-cli completion fish > ~/.config/fish/completions/expanso-cli.fish
# Reload fish completions
fish -c "source ~/.config/fish/completions/expanso-cli.fish"
#### Powershell:
# Add to your PowerShell profile:
expanso-cli completion powershell | Out-String | Invoke-Expression
# To make permanent, add to profile:
expanso-cli completion powershell >> $PROFILE
#### Troubleshooting:
If completions don't work:
- Ensure you restarted your shell after installation
- Verify you have an active profile connection (expanso-cli profile list)
- Check that the completion file was created in the correct location
- For zsh, verify the directory is in your $fpath: echo $fpath
### Options
```
-h, --help help for completion
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli](../) - Expanso CLI - Command-line interface for Expanso
* [expanso-cli completion bash](bash.md) - Generate bash completion script
* [expanso-cli completion fish](fish.md) - Generate fish completion script
* [expanso-cli completion powershell](powershell.md) - Generate powershell completion script
* [expanso-cli completion zsh](zsh.md) - Generate zsh completion script
## Bash
## `expanso-cli completion bash`
Generate bash completion script
### Synopsis
Generate the autocompletion script for bash.
To load completions in your current shell session:
source `<(expanso-cli completion bash)`
To load completions for every new session, execute once:
expanso-cli completion bash > ~/.local/share/bash-completion/completions/expanso-cli
```
expanso-cli completion bash [flags]
```
### Options
```
-h, --help help for bash
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli completion](./) - Generate shell completion scripts
## Fish
## `expanso-cli completion fish`
Generate fish completion script
### Synopsis
Generate the autocompletion script for fish.
To load completions in your current shell session:
expanso-cli completion fish | source
To load completions for every new session, execute once:
mkdir -p ~/.config/fish/completions
expanso-cli completion fish > ~/.config/fish/completions/expanso-cli.fish
You will need to start a new shell for this setup to take effect.
```
expanso-cli completion fish [flags]
```
### Options
```
-h, --help help for fish
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli completion](./) - Generate shell completion scripts
## Powershell
## `expanso-cli completion powershell`
Generate powershell completion script
### Synopsis
Generate the autocompletion script for powershell.
To load completions in your current shell session:
expanso-cli completion powershell | Out-String | Invoke-Expression
To load completions for every new session, add the output to your powershell profile:
expanso-cli completion powershell >> $PROFILE
```
expanso-cli completion powershell [flags]
```
### Options
```
-h, --help help for powershell
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli completion](./) - Generate shell completion scripts
## Zsh
## `expanso-cli completion zsh`
Generate zsh completion script
### Synopsis
Generate the autocompletion script for zsh.
To load completions in your current shell session:
source `<(expanso-cli completion zsh)`
To load completions for every new session, execute once:
# System-wide (requires sudo):
sudo mkdir -p /usr/local/share/zsh/site-functions
expanso-cli completion zsh | sudo tee /usr/local/share/zsh/site-functions/_expanso-cli
# OR user-level:
mkdir -p ~/.zsh/completions
expanso-cli completion zsh > ~/.zsh/completions/_expanso-cli
# Add to ~/.zshrc: `fpath=(~/.zsh/completions $fpath)`
You will need to start a new shell for this setup to take effect.
```
expanso-cli completion zsh [flags]
```
### Options
```
-h, --help help for zsh
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli completion](./) - Generate shell completion scripts
## Configuration
## `expanso-cli config`
Configuration management commands
### Synopsis
Inspect and understand runtime configuration from the configured endpoint.
#### What Are Config Commands?
Config commands allow you to view the current configuration settings
without needing direct access to config files or environment. This is useful for:
• Verifying configuration changes have been applied
• Understanding behavior and settings
• Debugging issues related to configuration
• Checking which configuration source is being used (CLI, env, file, defaults)
CONFIG vs PROFILE:
• Profiles: CLI connection settings (endpoint, auth, how to connect)
• Config: Service settings (scheduling, logging, resources, how services operate)
#### Available Commands:
• get: View the full configuration
• explain: View configuration with source information (where each value came from)
#### Common Workflows:
# View full configuration
expanso-cli config get
# See where configuration values came from
expanso-cli config explain
# Export configuration for reference
expanso-cli config get --format yaml > expanso-config.yaml
### Options
```
-h, --help help for config
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli](../) - Expanso CLI - Command-line interface for Expanso
* [expanso-cli config env](env.md) - List the environment variables expanso-cli understands
* [expanso-cli config explain](explain.md) - Show configuration values and their sources
* [expanso-cli config get](get.md) - Get the current configuration
## Env
## `expanso-cli config env`
List the environment variables expanso-cli understands
### Synopsis
List the environment variables expanso-cli reads, with the equivalent flag and
config key for each and whether it carries a secret.
Prefer environment variables over flags for secrets: a flag value is visible in
`ps` output and in /proc/``/cmdline on Linux. Use --json for a
machine-readable surface (for agents and scripts).
```
expanso-cli config env [flags]
```
### Examples
```
# Human-readable listing
expanso-cli config env
# Machine-readable surface
expanso-cli config env --json
```
### Options
```
-h, --help help for env
--json Emit the environment surface as JSON
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli config](./) - Configuration management commands
## Explain
## `expanso-cli config explain`
Show configuration values and their sources
### Synopsis
Display the current configuration values and where each value came from.
Configuration sources are shown in precedence order:
- cli: Command line flags
- env: Environment variables
- file: Configuration file
- dynamic: Dynamic configuration
- default: Built-in defaults
```
expanso-cli config explain [flags]
```
### Examples
```
# Show configuration with sources
expanso-cli config explain
# Show as JSON
expanso-cli config explain --output json
# Show as table
expanso-cli config explain --output table
```
### Options
```
-f, --format {table|json|yaml|csv} Output format (default table)
-h, --help help for explain
--no-header Hide table headers (table format only)
--no-style Disable colors and styling
-w, --wide Show full values without truncation (table format only)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli config](./) - Configuration management commands
## Get
## `expanso-cli config get`
Get the current configuration
### Synopsis
Retrieve and display the current configuration from the configured endpoint.
#### What This Shows:
The complete runtime configuration, including:
• API server settings (ports, timeouts, authentication)
• Scheduler configuration (intervals, worker counts)
• Node manager settings
• Logging configuration
• Telemetry and metrics settings
• Resource limits and quotas
#### When To Use This:
• Verify settings after deployment
• Understand default behavior and limits
• Debug unexpected behavior
• Document current configuration for reference
• Compare configurations across environments
#### Configuration Sources:
This command shows the effective configuration (final merged values).
To see where each value came from (CLI flags, env vars, config file, etc.),
use 'config explain' instead.
#### Output Formats:
• yaml: Human-readable, great for documentation (default)
• json: Machine-readable, great for parsing with jq
Note: This retrieves configuration from the configured endpoint, not your CLI profile settings.
For profile/connection settings, use 'profile current' instead.
```
expanso-cli config get [flags]
```
### Examples
```
# Get configuration as YAML
expanso-cli config get
# Get configuration as JSON
expanso-cli config get --format json
# Save configuration to file for reference
expanso-cli config get --format yaml > prod-config.yaml
# Extract specific value with jq
expanso-cli config get --format json | jq '.scheduler.evaluation_interval'
# Compare configurations between environments
diff `<(expanso-cli config get -p prod)` `<(expanso-cli config get -p staging)`
```
### Options
```
-f, --format {|json|yaml} Output format
-h, --help help for get
--no-style Disable colors and styling
--pretty Pretty print the output
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli config](./) - Configuration management commands
## Executions
## `expanso-cli execution`
Manage executions
### Synopsis
View and monitor job executions on edge nodes.
#### What Is An Execution?
An execution represents a job running on a specific node. Key characteristics:
• Unique combination of job ID, node ID, and job version
• Immutable snapshot of the job specification
• Tracks both desired state (control plane intent) and observed state (actual node state)
• Execution history maintained per job-node pair
#### Execution State Model:
Executions track two types of state:
Desired State (what control plane wants):
• pending: Should be scheduled
• running: Should be running
• stopped: Should be stopped
Observed State (actual state on node):
• pending: Scheduled but not started
• starting: Being initialized
• running: Actively executing
• degraded: Error occurred, will retry (non-terminal)
• complete: Successfully completed
• failed: Failed to run
• lost: Node disconnected
• stopping: In process of stopping
• stopped: Terminated
#### Understanding The Hierarchy:
• Job: The specification (what to run) - defined in YAML
• Evaluation: Scheduler decision (which nodes to assign)
• Execution: The running instance (where it's running) - one per job-node pair
Example:
Job "log-processor" → Evaluation #123 → 3 Executions:
- Execution exec-1 on node-us-west-1 (Running)
- Execution exec-2 on node-us-west-2 (Running)
- Execution exec-3 on node-us-east-1 (Failed)
#### Monitoring Patterns:
# List all executions
expanso-cli execution list
# Filter by job
expanso-cli execution list --job log-processor
# Filter by state
expanso-cli execution list --state failed
# View execution details (shows both desired and observed states)
expanso-cli execution describe exec-abc-123
# Track execution history (state changes over time)
expanso-cli execution history exec-abc-123
#### Common Troubleshooting:
# Find failed executions
expanso-cli execution list --state failed
# Check specific failure details
expanso-cli execution describe ``
# See which nodes a job is running on
expanso-cli job executions my-job
# See what's running on a specific node
expanso-cli node executions node-id-123
### Options
```
-h, --help help for execution
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli](../) - Expanso CLI - Command-line interface for Expanso
* [expanso-cli execution describe](describe.md) - Show detailed information about an execution
* [expanso-cli execution history](history.md) - Show history events for an execution
* [expanso-cli execution list](list.md) - List executions
## Describe
## `expanso-cli execution describe`
Show detailed information about an execution
### Synopsis
Display detailed information about a specific execution.
```
expanso-cli execution describe EXECUTION_ID [flags]
```
### Examples
```
# Describe an execution
expanso-cli execution describe exec-123
# Output as JSON
expanso-cli execution describe exec-123 --format json
# Output as YAML
expanso-cli execution describe exec-123 --format yaml
```
### Options
```
-f, --format {|json|yaml} Output format
-h, --help help for describe
--no-style Disable colors and styling
--pretty Pretty print the output
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli execution](./) - Manage executions
## History
## `expanso-cli execution history`
Show history events for an execution
### Synopsis
Display history events for a specific execution, showing lifecycle changes and state transitions.
```
expanso-cli execution history EXECUTION_ID [flags]
```
### Examples
```
# Show history for an execution
expanso-cli execution history exec-abc123
# Show history from last hour
expanso-cli execution history exec-abc123 --since 1h
# Show history from last 7 days
expanso-cli execution history exec-abc123 --since 7d
# Show history since a specific date (UTC)
expanso-cli execution history exec-abc123 --since 2024-10-15
# Show history since a specific date and time (UTC)
expanso-cli execution history exec-abc123 --since "2024-10-15 14:30:00"
# Show history since RFC3339 timestamp
expanso-cli execution history exec-abc123 --since 2024-10-15T14:00:00Z
# Show verbose output with sequence numbers
expanso-cli execution history exec-abc123 --verbose
# Limit results with pagination
expanso-cli execution history exec-abc123 --limit 20
# Output as JSON
expanso-cli execution history exec-abc123 --format json
```
### Options
```
-f, --format {table|json|yaml|csv} Output format (default table)
-h, --help help for history
-l, --limit int Maximum number of results to return (default 50)
--next-token string Continuation token for pagination
--no-header Hide table headers (table format only)
--no-style Disable colors and styling
--since string Filter events after this time (duration: 1h, 7d; date: 2024-10-15; or RFC3339)
-v, --verbose Show verbose output including sequence numbers
-w, --wide Show full values without truncation (table format only)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
```
### SEE ALSO
* [expanso-cli execution](./) - Manage executions
## List
## `expanso-cli execution list`
List executions
### Synopsis
List all executions with optional filtering and pagination.
```
expanso-cli execution list [flags]
```
### Examples
```
# List all executions
expanso-cli execution list
# List executions for a specific job
expanso-cli execution list --job-id job-123
# List executions for a specific job version
expanso-cli execution list --job-id job-123 --job-version 3
# List executions on specific nodes
expanso-cli execution list --node-id node-456
expanso-cli execution list --node-id node-456 --node-id node-789
# List executions in a namespace
expanso-cli execution list --namespace production
# List executions with specific states
expanso-cli execution list --state running --state pending
# Limit results with pagination
expanso-cli execution list --limit 10 --token abc123
```
### Options
```
-f, --format {table|json|yaml|csv} Output format (default table)
-h, --help help for list
--job-id string Filter by job ID
--job-version uint Filter by job version (requires --job-id)
-l, --limit int Maximum number of results to return (default 50)
-n, --namespace string Filter by namespace
--next-token string Continuation token for pagination
--no-header Hide table headers (table format only)
--no-style Disable colors and styling
--node-id strings Filter by node ID (can specify multiple)
--order string Order direction (asc, desc)
--order-by string Field to order by
--state execution state Filter by execution state
-w, --wide Show full values without truncation (table format only)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli execution](./) - Manage executions
## Health
## `expanso-cli health`
Check health
### Synopsis
Check service liveness.
This is the unauthenticated probe response and reports only whether the service
is healthy. For version, uptime, build info, and per-component status, use:
expanso-cli status
```
expanso-cli health [flags]
```
### Examples
```
# Check health
expanso-cli health
# Get health status as JSON
expanso-cli health --format json
# Get health status as YAML
expanso-cli health --format yaml
```
### Options
```
-f, --format {|json|yaml} Output format
-h, --help help for health
--no-style Disable colors and styling
--pretty Pretty print the output
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli](../) - Expanso CLI - Command-line interface for Expanso
## Jobs
## `expanso-cli job`
Manage jobs
### Synopsis
Manage jobs in Expanso.
#### What Is A Job?
A job is a declarative specification for a data processing pipeline that runs on your edge nodes.
Jobs are defined in YAML files containing:
• name: Unique identifier for the job
• type: Job type (currently only "pipeline" is supported)
• config: Pipeline configuration (input, processors, output)
• selector: Which nodes should run this job (label-based matching)
JOB vs PIPELINE:
Jobs are the orchestration unit - they define WHAT runs and WHERE.
Pipelines are the workload type - they define data processing logic.
Today, jobs with type="pipeline" are the primary use case.
#### Job Lifecycle:
1. Deploy: Submit job spec to the control plane (validates and stores)
2. Evaluate: Scheduler finds matching nodes based on selector
3. Execute: Job runs on selected nodes (long-running, restarts on failure)
4. Monitor: Track execution status and logs
5. Update: Deploy new version (scheduler re-evaluates and updates executions)
#### Pipeline Structure:
Pipelines process data through three stages:
• Input: Where data comes from (files, HTTP, message queues, etc.)
• Processors: Transformations, filtering, enrichment (optional)
• Output: Where data goes (S3, databases, APIs, stdout, etc.)
#### Node Selectors:
Target specific nodes using label-based selectors:
selector:
match_labels:
region: us-west
env: production
#### Common Workflows:
# Deploy a new job
expanso-cli job deploy log-processor.yaml
# List all jobs
expanso-cli job list
# Check job status
expanso-cli job describe log-processor
# See where job is running
expanso-cli execution list --job log-processor
# Update a job (new version triggers re-evaluation)
expanso-cli job deploy log-processor.yaml
# Stop a running job
expanso-cli job stop log-processor
### Options
```
-h, --help help for job
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli](../) - Expanso CLI - Command-line interface for Expanso
* [expanso-cli job delete](delete.md) - Delete a job
* [expanso-cli job deploy](deploy.md) - Deploy a job from a file
* [expanso-cli job describe](describe.md) - Show detailed information about a job
* [expanso-cli job diff](diff.md) - Show differences between local and deployed job
* [expanso-cli job executions](executions.md) - List executions for a job
* [expanso-cli job history](history.md) - Show history events for a job
* [expanso-cli job list](list.md) - List jobs
* [expanso-cli job logs](logs.md) - Shows the logs of a job in realtime
* [expanso-cli job pause-rollout](pause-rollout.md) - Pause an active rollout for a job
* [expanso-cli job rerun](rerun.md) - Restart a job with its current configuration
* [expanso-cli job resume-rollout](resume-rollout.md) - Resume a paused rollout for a job
* [expanso-cli job rollback](rollback.md) - Rollback a job to a previous version
* [expanso-cli job stop](stop.md) - Stop a running job
* [expanso-cli job validate](validate.md) - Validate a job specification
* [expanso-cli job versions](versions.md) - List all versions of a job
* [expanso-cli job versions-diff](versions-diff.md) - Compare two versions of a job
## Delete
## `expanso-cli job delete`
Delete a job
### Synopsis
Soft-delete a job and stop all its executions. The job data is preserved for audit purposes but excluded from default listings.
```
expanso-cli job delete JOB_ID_OR_NAME [flags]
```
### Examples
```
# Delete a job by name
expanso-cli job delete my-job
# Delete a job by ID
expanso-cli job delete job-abc123
# Skip confirmation prompt
expanso-cli job delete my-job --yes
# Force delete even if not in deletable state
expanso-cli job delete my-job --force
# Skip confirmation and bypass state validation
expanso-cli job delete my-job --yes --force
# Delete with a custom reason
expanso-cli job delete my-job --reason "No longer needed"
# View deleted jobs
expanso-cli job list --states deleted
```
### Options
```
-f, --force Force deletion even if job is not in deletable state
-h, --help help for delete
--reason string Reason for deletion
-y, --yes Skip confirmation prompt
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli job](./) - Manage jobs
## Deploy
## `expanso-cli job deploy`
Deploy a job from a file
### Synopsis
Deploy a new job or update an existing job from a YAML or JSON file.
#### What Happens When You Deploy:
1. CLI sends job specification to the control plane
2. Control plane validates the job (checks syntax, required fields)
3. Control plane stores the job and returns immediately
4. Assignment happens asynchronously:
- Control plane creates an evaluation
- Scheduler finds nodes matching the job's selector
- Executions are created on matching nodes
The deploy command returns after validation and storage, not after
assignment. Use 'job describe' and 'execution list' to check status.
#### Job Identification:
By default, jobs are identified by name + namespace (from the spec):
• Updates if a job with that name exists
• Creates if no job with that name exists
• Cannot rename jobs (changing the name creates a new job)
Use --id to explicitly target a job by its ID:
• Useful for renaming jobs (name in spec can be different)
• Requires job to exist (fails with 404 if not found)
• Prevents accidental creation of duplicate jobs
#### Job Specification Format:
Jobs are defined in YAML or JSON with these required fields:
• name: Job identifier (DNS-1123 label, max 63 chars)
• type: Job type (currently only "pipeline")
• config: Type-specific configuration
- For pipelines: input, pipeline (processors), output sections
• selector: Node selection criteria (match_labels, match_expressions)
For complete job specification reference and examples, see the Pipeline Guide.
```
expanso-cli job deploy FILE [flags]
```
### Examples
```
# Create a minimal job specification
cat > log-processor.yaml <`
```
### Options
```
-f, --format {table|json|yaml|csv} Output format (default table)
-h, --help help for executions
--job-version uint Filter by job version
--limit int Maximum number of results to return (default 50)
--next-token string Continuation token for pagination
--no-header Hide table headers (table format only)
--no-style Disable colors and styling
--node-id stringArray Filter by node ID
--order string Order direction (asc, desc)
--order-by string Field to order by
--state execution state Filter by execution state
-w, --wide Show full values without truncation (table format only)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli job](./) - Manage jobs
## History
## `expanso-cli job history`
Show history events for a job
### Synopsis
Display history events for a specific job, showing lifecycle changes and state transitions.
```
expanso-cli job history JOB_ID_OR_NAME [flags]
```
### Examples
```
# Show history for a job
expanso-cli job history my-job
# Show history from last hour
expanso-cli job history my-job --since 1h
# Show history from last 7 days
expanso-cli job history my-job --since 7d
# Show history since a specific date (UTC)
expanso-cli job history my-job --since 2024-10-15
# Show history since a specific date and time (UTC)
expanso-cli job history my-job --since "2024-10-15 14:30:00"
# Show history since RFC3339 timestamp
expanso-cli job history my-job --since 2024-10-15T14:00:00Z
# Show verbose output with sequence numbers
expanso-cli job history my-job --verbose
# Limit results with pagination
expanso-cli job history my-job --limit 20
# Output as JSON
expanso-cli job history my-job --format json
```
### Options
```
-f, --format {table|json|yaml|csv} Output format (default table)
-h, --help help for history
-l, --limit int Maximum number of results to return (default 50)
-n, --namespace string Job namespace
--next-token string Continuation token for pagination
--no-header Hide table headers (table format only)
--no-style Disable colors and styling
--since string Filter events after this time (duration: 1h, 7d; date: 2024-10-15; or RFC3339)
-v, --verbose Show verbose output including sequence numbers
-w, --wide Show full values without truncation (table format only)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
```
### SEE ALSO
* [expanso-cli job](./) - Manage jobs
## List
## `expanso-cli job list`
List jobs
### Synopsis
List all jobs with optional filtering and pagination.
```
expanso-cli job list [flags]
```
### Examples
```
# List all jobs
expanso-cli job list
# List jobs in a specific namespace
expanso-cli job list --namespace production
# List jobs with specific types
expanso-cli job list --type daemon --type system
# List jobs with specific states
expanso-cli job list --state running --state pending
# List jobs with labels
expanso-cli job list --label env=prod --label team=infra
# Limit results with pagination
expanso-cli job list --limit 10
# Continue to next page with token
expanso-cli job list --limit 10 --token ``
```
### Options
```
-f, --format {table|json|yaml|csv} Output format (default table)
-h, --help help for list
-L, --label strings Filter by labels (format: key=value)
-l, --limit int Maximum number of results to return (default 50)
-n, --namespace string Filter by namespace
--next-token string Continuation token for pagination
--no-header Hide table headers (table format only)
--no-style Disable colors and styling
--order string Order direction (asc, desc)
--order-by string Field to order by
--state job state Filter by job state
--type strings Filter by job type (daemon, system, ops)
-w, --wide Show full values without truncation (table format only)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli job](./) - Manage jobs
## Logs
## `expanso-cli job logs`
Shows the logs of a job in realtime
### Synopsis
Stream live logs for a running job. Logs flow from the orchestrator's WebSocket endpoint; closing it stops streaming.
```
expanso-cli job logs JOB_NAME [flags]
```
### Examples
```
# Show logs for a job (orchestrator picks a node)
expanso-cli job logs my-job
# Show logs for a job from a specific node
expanso-cli job logs my-job --node node1-id
```
### Options
```
-f, --format {|json|yaml} Output format
-h, --help help for logs
--no-style Disable colors and styling
--node string Specific edge node to stream from; defaults to orchestrator's pick.
--pretty Pretty print the output
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli job](./) - Manage jobs
## Pause-rollout
## `expanso-cli job pause-rollout`
Pause an active rollout for a job
### Synopsis
Pause an active rollout for a job.
When a rollout is paused:
- No new executions are scheduled for the new version
- Existing executions continue running (not stopped)
- The rollout can be resumed later with 'resume-rollout'
This is useful for investigating issues during a rolling deployment without
triggering a full rollback.
```
expanso-cli job pause-rollout JOB_ID_OR_NAME [flags]
```
### Examples
```
# Pause rollout by job name
expanso-cli job pause-rollout my-job
# Pause rollout with a reason
expanso-cli job pause-rollout my-job --reason "investigating performance issue"
# Dry run to see what would happen
expanso-cli job pause-rollout my-job --dry-run
```
### Options
```
--dry-run Validate without applying
-h, --help help for pause-rollout
--namespace string Job namespace
--reason string Reason for pausing the rollout
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli job](./) - Manage jobs
## Rerun
## `expanso-cli job rerun`
Restart a job with its current configuration
### Synopsis
Restart a job by re-executing it with the same spec.
This creates a new version with rollout type 'restart' and triggers
a new evaluation to re-deploy executions.
To deploy a previous version's spec, use 'expanso-cli job rollback' instead.
```
expanso-cli job rerun JOB_ID_OR_NAME [flags]
```
### Examples
```
# Restart a job by name
expanso-cli job rerun my-job
# Restart a job by ID
expanso-cli job rerun job-abc123
# Restart a job in a specific namespace
expanso-cli job rerun my-job --namespace production
```
### Options
```
-h, --help help for rerun
--namespace string Job namespace
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli job](./) - Manage jobs
## Resume-rollout
## `expanso-cli job resume-rollout`
Resume a paused rollout for a job
### Synopsis
Resume a paused rollout for a job.
When a rollout is resumed:
- The rollout continues from where it was paused
- New executions are scheduled according to the rollout strategy
- Wave-based rollouts continue with the next wave
Use 'describe' to check the current rollout state before resuming.
```
expanso-cli job resume-rollout JOB_ID_OR_NAME [flags]
```
### Examples
```
# Resume rollout by job name
expanso-cli job resume-rollout my-job
# Resume rollout with a reason
expanso-cli job resume-rollout my-job --reason "issue resolved, continuing deployment"
# Dry run to see what would happen
expanso-cli job resume-rollout my-job --dry-run
```
### Options
```
--dry-run Validate without applying
-h, --help help for resume-rollout
--namespace string Job namespace
--reason string Reason for resuming the rollout
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli job](./) - Manage jobs
## Rollback
## `expanso-cli job rollback`
Rollback a job to a previous version
### Synopsis
Rollback a job to a previous version.
This creates a new version with the spec from the target version and triggers
a new rollout. The job version number continues to increment (monotonic versioning),
but the spec content comes from the target version.
If no --to-version is specified, it defaults to the last stable version
(the RollbackToVersion from the current rollout status).
Example:
Current: version 3 (new spec)
Rollback to version 1
Result: version 4 (with version 1's spec)
```
expanso-cli job rollback JOB_ID_OR_NAME [flags]
```
### Examples
```
# Rollback to the previous stable version
expanso-cli job rollback my-job
# Rollback to a specific version
expanso-cli job rollback my-job --to-version 1
# Rollback with a reason
expanso-cli job rollback my-job --reason "v3 caused issues in production"
# Dry run to see what would happen
expanso-cli job rollback my-job --to-version 1 --dry-run
# Force rollback without confirmation
expanso-cli job rollback my-job --force
```
### Options
```
--dry-run Validate without applying
-f, --force Force rollback without confirmation
-h, --help help for rollback
--namespace string Job namespace
--reason string Reason for rollback
--to-version uint Target version to rollback to (default: previous stable version)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli job](./) - Manage jobs
## Stop
## `expanso-cli job stop`
Stop a running job
### Synopsis
Stop all executions of a running job.
```
expanso-cli job stop JOB_ID_OR_NAME [flags]
```
### Examples
```
# Stop a job by name
expanso-cli job stop my-job
# Stop a job by ID
expanso-cli job stop job-abc123
# Force stop without confirmation
expanso-cli job stop my-job --force
# Stop a job in a specific namespace
expanso-cli job stop my-job --namespace production
```
### Options
```
-f, --force Force stop without confirmation
-h, --help help for stop
--namespace string Job namespace
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli job](./) - Manage jobs
## Validate
## `expanso-cli job validate`
Validate a job specification
### Synopsis
Validate job specification syntax and structure.
By default, performs both client-side and server-side validation.
Client-side validation checks syntax and structure (works offline).
Server-side validation performs comprehensive checks against the cluster.
Use --offline to skip server-side validation (useful for CI or when server is unavailable).
```
expanso-cli job validate FILE [flags]
```
### Examples
```
# Validate a job file (client + server)
expanso-cli job validate job.yaml
# Validate from stdin
cat job.yaml | expanso-cli job validate -
# Validate offline (client-side only)
expanso-cli job validate job.yaml --offline
```
### Options
```
-h, --help help for validate
--offline Skip server-side validation (client-side only)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli job](./) - Manage jobs
## Versions
## `expanso-cli job versions`
List all versions of a job
### Synopsis
List all versions of a job showing the history of changes.
```
expanso-cli job versions JOB_ID_OR_NAME [flags]
```
### Examples
```
# List all versions of a job
expanso-cli job versions my-job
# Limit results with pagination
expanso-cli job versions my-job --limit 10
# Continue to next page with token
expanso-cli job versions my-job --limit 10 --token ``
```
### Options
```
-f, --format {table|json|yaml|csv} Output format (default table)
-h, --help help for versions
--limit int Maximum number of results to return (default 50)
--namespace string Namespace to search in
--next-token string Continuation token for pagination
--no-header Hide table headers (table format only)
--no-style Disable colors and styling
-w, --wide Show full values without truncation (table format only)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli job](./) - Manage jobs
## Versions-diff
## `expanso-cli job versions-diff`
Compare two versions of a job
### Synopsis
Compare two historical versions of a job and show the differences.
```
expanso-cli job versions-diff JOB_ID_OR_NAME [flags]
```
### Examples
```
# Compare version 1 to version 3
expanso-cli job versions-diff my-job --from 1 --to 3
# Compare version 1 to latest version
expanso-cli job versions-diff my-job --from 1
# Compare versions with namespace
expanso-cli job versions-diff my-job --from 1 --to 2 --namespace production
```
### Options
```
--from uint Base version number (required)
-h, --help help for versions-diff
--namespace string Namespace to search in
--to uint Target version number (defaults to latest)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli job](./) - Manage jobs
## Nodes
## `expanso-cli node`
Manage nodes
### Synopsis
View and manage edge nodes in your Expanso deployment.
#### What Is A Node?
A node is an edge agent (expanso-edge) running on your infrastructure that connects to
the control plane. Each node:
• Connects securely to the control plane via NATS transport
• Reports its identity, labels, and resource capabilities
• Executes jobs assigned by the control plane based on selectors
• Sends execution status, logs, and metrics
• Maintains connection and automatically reconnects if disconnected
#### Node Lifecycle:
1. Bootstrap: Node obtains credentials from bootstrap service (one-time)
2. Connect: Node establishes secure connection to control plane
3. Register: Node reports identity, labels, capabilities, and resources
4. Ready: Node is available to receive job assignments
5. Execute: Node runs assigned jobs
6. Disconnect: Connection lost (node shown as "disconnected" until reconnected)
#### Node Labels:
Nodes are tagged with labels for targeting:
• System labels: region, zone, os, arch
• Custom labels: env=production, datacenter=us-west-1
• Used in job selectors to control where jobs run
#### Node Capabilities:
Nodes report their capabilities:
• Available resources (CPU, memory, disk)
• Supported job types
• Network connectivity
• Storage capabilities
#### Common Tasks:
# List all connected nodes
expanso-cli node list
# Filter by label
expanso-cli node list --label env=production
# View detailed node information
expanso-cli node describe node-id-123
# See what's running on a node
expanso-cli node executions node-id-123
# Check node health and resource usage
expanso-cli node stats
### Options
```
-h, --help help for node
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli](../) - Expanso CLI - Command-line interface for Expanso
* [expanso-cli node delete](delete.md) - Delete a node
* [expanso-cli node describe](describe.md) - Show detailed information about a node
* [expanso-cli node executions](executions.md) - List executions on a node
* [expanso-cli node list](list.md) - List nodes
* [expanso-cli node metrics](metrics.md) - Show recent pipeline metrics for a node
* [expanso-cli node resources](resources.md) - Show recent resource usage (CPU/memory/disk) for a node
* [expanso-cli node stats](stats.md) - Get aggregate statistics for nodes
## Delete
## `expanso-cli node delete`
Delete a node
### Synopsis
Soft-delete a node and mark it as deleted. The node data is preserved for audit purposes and will be permanently removed after the garbage collection retention period.
```
expanso-cli node delete NODE_ID_OR_NAME [flags]
```
### Examples
```
# Delete a disconnected node
expanso-cli node delete my-node
# Delete a node by ID
expanso-cli node delete node-abc123
# Skip confirmation prompt
expanso-cli node delete my-node --yes
# Force delete a connected node (dangerous - node will reconnect if still online)
expanso-cli node delete my-node --force
# Skip confirmation and force deletion
expanso-cli node delete my-node --yes --force
# Delete with a custom reason
expanso-cli node delete my-node --reason "Hardware decommissioned"
# View deleted nodes
expanso-cli node list --state deleted
```
### Options
```
-f, --force Force deletion even if node is connected
-h, --help help for delete
--reason string Reason for deletion
-y, --yes Skip confirmation prompt
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli node](./) - Manage nodes
## Describe
## `expanso-cli node describe`
Show detailed information about a node
### Synopsis
Display detailed information about a specific node including its resources and current state.
```
expanso-cli node describe NODE_ID [flags]
```
### Examples
```
# Describe a node
expanso-cli node describe node-123
# Output as JSON
expanso-cli node describe node-123 --format json
# Output as YAML
expanso-cli node describe node-123 --format yaml
```
### Options
```
-f, --format {|json|yaml} Output format
-h, --help help for describe
--no-style Disable colors and styling
--pretty Pretty print the output
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli node](./) - Manage nodes
## Executions
## `expanso-cli node executions`
List executions on a node
### Synopsis
List all executions running on a specific node with optional filtering.
```
expanso-cli node executions NODE_ID [flags]
```
### Examples
```
# List all executions on a node
expanso-cli node executions node-123
# List executions with specific states
expanso-cli node executions node-123 --state running --state pending
# List executions for a specific job
expanso-cli node executions node-123 --job-id job-456
# Limit results with pagination
expanso-cli node executions node-123 --limit 10 --next-token abc123
```
### Options
```
-f, --format {table|json|yaml|csv} Output format (default table)
-h, --help help for executions
--job-id string Filter by job ID
--limit int Maximum number of results to return (default 50)
--next-token string Continuation token for pagination
--no-header Hide table headers (table format only)
--no-style Disable colors and styling
--state execution state Filter by execution state
-w, --wide Show full values without truncation (table format only)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli node](./) - Manage nodes
## List
## `expanso-cli node list`
List nodes
### Synopsis
List all nodes with optional filtering and pagination.
```
expanso-cli node list [flags]
```
### Examples
```
# List all nodes
expanso-cli node list
# List nodes with specific states
expanso-cli node list --state healthy --state degraded
# List nodes with labels
expanso-cli node list --label region=us-west --label env=prod
# Limit results with pagination
expanso-cli node list --limit 10
# Continue to next page with token
expanso-cli node list --limit 10 --next-token ``
# Sort results
expanso-cli node list --order-by name --order asc
```
### Options
```
-f, --format {table|json|yaml|csv} Output format (default table)
-h, --help help for list
-L, --label strings Filter by labels (format: key=value)
-l, --limit int Maximum number of results to return (default 50)
--next-token string Continuation token for pagination
--no-header Hide table headers (table format only)
--no-style Disable colors and styling
--order string Order direction (asc, desc)
--order-by string Field to order by
--state node connection state Filter by node connection state
-w, --wide Show full values without truncation (table format only)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli node](./) - Manage nodes
## Metrics
## `expanso-cli node metrics`
Show recent pipeline metrics for a node
### Synopsis
Show the retained window of curated pipeline metrics for a node: per-component
throughput and latency, collected on the edge and delivered over the control plane.
By default it summarizes every pipeline with data on the node; --pipeline drills
into one pipeline's per-component detail. With --follow (requires --pipeline) it
tails the pipeline's live samples until interrupted.
```
expanso-cli node metrics NODE_ID [flags]
```
### Examples
```
# All pipelines on a node
expanso-cli node metrics node-123
# One pipeline, per-component detail
expanso-cli node metrics node-123 --pipeline j-abc123
# Live tail of one pipeline
expanso-cli node metrics node-123 --pipeline j-abc123 --follow
# JSON output
expanso-cli node metrics node-123 --format json
```
### Options
```
--follow Stream live samples until interrupted (Ctrl-C); requires --pipeline
-f, --format {table|json|yaml|csv} Output format (default table)
-h, --help help for metrics
--no-header Hide table headers (table format only)
--no-style Disable colors and styling
--pipeline string Show one pipeline's per-component detail instead of all pipelines on the node
-w, --wide Show full values without truncation (table format only)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli node](./) - Manage nodes
## Resources
## `expanso-cli node resources`
Show recent resource usage (CPU/memory/disk) for a node
### Synopsis
Show the retained window of a node's resource usage -- CPU, memory, and disk --
as reported by heartbeats and served from the orchestrator's in-memory store.
With --follow it tails the node's live resource samples until interrupted.
```
expanso-cli node resources NODE_ID [flags]
```
### Examples
```
# Recent resource usage for a node
expanso-cli node resources node-123
# Live tail
expanso-cli node resources node-123 --follow
# JSON output
expanso-cli node resources node-123 --format json
```
### Options
```
--follow Stream live samples until interrupted (Ctrl-C)
-f, --format {table|json|yaml|csv} Output format (default table)
-h, --help help for resources
--no-header Hide table headers (table format only)
--no-style Disable colors and styling
-w, --wide Show full values without truncation (table format only)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli node](./) - Manage nodes
## Stats
## `expanso-cli node stats`
Get aggregate statistics for nodes
### Synopsis
Get aggregate statistics across all nodes in your workspace including resource usage, connection states, and distribution by OS/architecture.
```
expanso-cli node stats [flags]
```
### Examples
```
# Get stats for all nodes
expanso-cli node stats
# Get stats for connected nodes only
expanso-cli node stats --state connected
# Get stats for nodes with specific labels
expanso-cli node stats --label region=us-west --label env=prod
# Output as JSON
expanso-cli node stats --format json
```
### Options
```
-f, --format {table|json|yaml|csv} Output format (default table)
-h, --help help for stats
--label strings Filter by labels (format: key=value)
--no-header Hide table headers (table format only)
--no-style Disable colors and styling
--state node connection state Filter by node connection state
-w, --wide Show full values without truncation (table format only)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli node](./) - Manage nodes
## Profiles
## `expanso-cli profile`
Manage client connection profiles
### Synopsis
Manage named profiles for connecting to different Expanso endpoints.
#### Why Profiles?
Expanso is a managed service - you can run it in Expanso Cloud or your own infrastructure.
Profiles store connection details (endpoint, authentication, TLS settings) so you don't need to
specify --endpoint and auth flags with every command.
#### Common Patterns:
• Multiple environments: Save profiles for dev, staging, and production
• Team collaboration: Share profile configs (without credentials) via dotfiles
• Quick switching: Use 'profile select' to switch between endpoints instantly
#### Profile Storage:
Profiles are stored as YAML files in ~/.expanso/cli-client/profiles/
Current profile selection is stored in ~/.expanso/cli-client/current-profile
WHAT'S STORED IN A PROFILE:
• Endpoint URL (API server address)
• Authentication credentials (tokens, certs)
• TLS configuration
• Request timeout settings
### Examples
```
# Save a new profile for production
expanso-cli profile save prod --endpoint api.expanso.io --token YOUR_TOKEN --select
# Save a development profile
expanso-cli profile save dev --endpoint dev.expanso.example.com --token DEV_TOKEN
# List all profiles
expanso-cli profile list
# Switch to a different profile
expanso-cli profile select dev
# Show current profile details
expanso-cli profile current
# View a specific profile
expanso-cli profile show prod
```
### Options
```
-h, --help help for profile
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli](../) - Expanso CLI - Command-line interface for Expanso
* [expanso-cli profile current](current.md) - Display the current profile
* [expanso-cli profile delete](delete.md) - Delete a profile
* [expanso-cli profile list](list.md) - List all profiles
* [expanso-cli profile save](save.md) - Save a profile (create new or update existing)
* [expanso-cli profile select](select.md) - Set the current profile
* [expanso-cli profile show](show.md) - Show profile details
## Current
## `expanso-cli profile current`
Display the current profile
### Synopsis
Display detailed information about the currently selected profile.
#### What This Shows:
• Profile name
• Endpoint URL (control plane or edge node)
• Authentication configuration
• TLS/SSL settings
• Timeout configuration
• Profile metadata (description, last updated)
#### Why Check Current Profile:
• Verify which environment you're connected to before running commands
• Confirm profile settings before critical operations
• Debug connection issues
• Check if profile was overridden by environment variable
#### Environment Override:
If EXPANSO_CLI_PROFILE environment variable is set, it overrides the selected
profile. This command shows if the current profile came from the environment
or from 'profile select'.
#### Output Formats:
Use --format flag to get machine-readable output:
• json: For parsing with jq or other tools
• yaml: For readability or config file creation
```
expanso-cli profile current [flags]
```
### Options
```
-f, --format {|json|yaml} Output format
-h, --help help for current
--no-style Disable colors and styling
--pretty Pretty print the output
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli profile](./) - Manage client connection profiles
## Delete
## `expanso-cli profile delete`
Delete a profile
### Synopsis
Delete a connection profile.
#### What Gets Deleted:
Permanently removes the profile configuration file from:
~/.expanso/cli-client/profiles/PROFILE_NAME.yaml
This includes all settings: endpoint URL, authentication credentials,
TLS configuration, and metadata.
#### When To Delete:
• Decommissioned environment no longer exists
• Credentials have been rotated and profile needs to be recreated
• Cleaning up old test/temporary profiles
• Removing profiles for environments you no longer access
#### Safety Checks:
• Asks for confirmation before deleting (unless --force is used)
• Warns if you're deleting the currently selected profile
• After deleting current profile, you'll need to select another
#### Recovering:
Profile deletion is permanent. If you might need the profile again,
consider using 'profile show' to export it before deleting:
expanso-cli profile show old-env > backup.json
```
expanso-cli profile delete PROFILE_NAME [flags]
```
### Examples
```
# Delete a profile (asks for confirmation)
expanso-cli profile delete old-staging
# Delete without confirmation
expanso-cli profile delete temp-test --force
# Backup before deleting
expanso-cli profile show old-env > old-env-backup.json
expanso-cli profile delete old-env
```
### Options
```
-f, --force Force deletion without confirmation
-h, --help help for delete
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli profile](./) - Manage client connection profiles
## List
## `expanso-cli profile list`
List all profiles
### Synopsis
List all configured connection profiles.
WHAT YOU SEE (default view):
• Profile names
• Current profile indicator (marked with *)
• Endpoint URLs (control plane or edge nodes)
• Authentication type (api-key or none)
• Last updated timestamp
WHAT YOU SEE (--wide mode):
All default columns plus:
• TLS status (secure or insecure)
• Profile descriptions
#### Use Cases:
• See all available environments
• Find which profile is currently active
• Verify endpoint configurations before switching
• Check when profiles were last modified
The current profile (marked with *) is used when you don't specify
-p/--profile flag with commands.
```
expanso-cli profile list [flags]
```
### Examples
```
# List profiles in table format
expanso-cli profile list
# Output as YAML
expanso-cli profile list -f yaml
# Output as JSON
expanso-cli profile list -f json
# Show all columns
expanso-cli profile list --wide
```
### Options
```
-f, --format {table|json|yaml|csv} Output format (default table)
-h, --help help for list
--no-header Hide table headers (table format only)
--no-style Disable colors and styling
-w, --wide Show full values without truncation (table format only)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli profile](./) - Manage client connection profiles
## Save
## `expanso-cli profile save`
Save a profile (create new or update existing)
### Synopsis
Save a connection profile for an Expanso environment.
#### What Are Profiles?
Profiles store connection settings for different Expanso environments
(production, staging, development, etc.). Each profile contains:
• Expanso endpoint URL (control plane or edge node)
• Authentication credentials (API key or bearer token)
• TLS configuration
• Default timeout settings
#### Why Use Profiles?
Instead of specifying --endpoint and --api-key with every command, save
a profile once and reference it by name. Switch between environments
easily without re-entering credentials.
#### Profile Behavior:
• Save new profile: Creates profile with specified configuration
• Update existing: Merges new settings with existing profile
• Copy from existing: Use --from to copy another profile as starting point
• Auto-select: Use --select flag to make this the active profile
#### Endpoint Convenience:
You can specify just the hostname and the CLI will automatically add
the scheme (https://) and port (:443) if not provided:
--endpoint api.expanso.io → api.expanso.io:443 over HTTPS
#### Profiles Location:
Profiles are stored in ~/.expanso/cli-client/profiles/
```
expanso-cli profile save PROFILE_NAME [flags]
```
### Examples
```
# Create a profile for production with an API key (scheme and port are auto-added)
expanso-cli profile save prod --endpoint api.expanso.io --api-key exp_ak_YOUR_KEY --select
# Create a profile for development environment
expanso-cli profile save dev --endpoint dev.expanso.example.com --api-key exp_ak_DEV_KEY
# Copy from existing profile
expanso-cli profile save staging --from prod --endpoint staging.expanso.example.com
# You can still use full URLs if needed
expanso-cli profile save custom --endpoint https://custom.expanso.example.com:8080
```
### Options
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
--description string Profile description
-e, --endpoint string API endpoint URL
--from string Copy settings from an existing profile
-h, --help help for save
-k, --insecure Skip TLS certificate verification
--select Set as current profile
--timeout string Request timeout duration
```
### Options inherited from parent commands
```
-p, --profile string Profile to use for configuration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli profile](./) - Manage client connection profiles
## Select
## `expanso-cli profile select`
Set the current profile
### Synopsis
Set the current profile to use for all subsequent commands.
#### What Happens:
When you select a profile, it becomes the default connection configuration
for all CLI commands. The CLI will:
• Use this profile's endpoint when connecting to Expanso
• Use this profile's authentication credentials
• Apply this profile's TLS/SSL settings
• Use this profile's timeout configuration
#### Why Select A Profile?
Instead of specifying -p/--profile with every command, select your target
environment once. All subsequent commands automatically use that profile.
#### Switching Environments:
To work with a different environment, simply select a different profile:
expanso-cli profile select staging # Switch to staging
expanso-cli job list # Lists jobs from staging
expanso-cli profile select prod # Switch to production
expanso-cli job list # Lists jobs from production
You can also override the current profile on a per-command basis using
the -p/--profile flag without changing your selection.
```
expanso-cli profile select PROFILE_NAME [flags]
```
### Examples
```
# Select production profile
expanso-cli profile select production
# Switch to development
expanso-cli profile select dev
# Check which profile is currently selected
expanso-cli profile current
```
### Options
```
-h, --help help for select
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli profile](./) - Manage client connection profiles
## Show
## `expanso-cli profile show`
Show profile details
### Synopsis
Display the full configuration for a profile in YAML format.
#### What You See:
Complete profile configuration including:
• Endpoint URL
• Authentication configuration (tokens are redacted by default)
• TLS settings
• Timeout settings
• Description and metadata
#### Token Security:
By default, authentication tokens are redacted (shown as "tok_****...xyz").
Use --show-token flag to display the full token when needed for export or debugging.
#### Use Cases:
• Verify profile configuration before using
• Debug connection issues
• Export profile for backup or sharing
• Check which authentication method is configured
• Review TLS settings
#### Output Format:
Output is YAML format to enable easy parsing and export. Use shell
redirection (>) to save to a file for backup or transfer.
```
expanso-cli profile show PROFILE_NAME [flags]
```
### Examples
```
# Show production profile details (tokens redacted)
expanso-cli profile show production
# Show profile with full token
expanso-cli profile show production --show-token
# Export profile to file (for backup)
expanso-cli profile show production --show-token > prod-profile.yaml
```
### Options
```
-h, --help help for show
--show-token Display full authentication token (not redacted)
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli profile](./) - Manage client connection profiles
## Status
## `expanso-cli status`
Get status
### Synopsis
Get detailed status including resource usage, jobs, and metrics (output varies by endpoint type).
```
expanso-cli status [flags]
```
### Examples
```
# Get status
expanso-cli status
# Get status as JSON
expanso-cli status --format json
# Get status as YAML
expanso-cli status --format yaml
```
### Options
```
-f, --format {|json|yaml} Output format
-h, --help help for status
--no-style Disable colors and styling
--pretty Pretty print the output
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli](../) - Expanso CLI - Command-line interface for Expanso
## Version
## `expanso-cli version`
Print version information
### Synopsis
Display the version, git commit, and build date of the Expanso CLI.
```
expanso-cli version [flags]
```
### Options
```
-h, --help help for version
```
### Options inherited from parent commands
```
--api-key string API key for authentication (e.g., exp_ak_...). Env: EXPANSO_CLI_AUTH_API_KEY (preferred; flag values show in ps output)
-e, --endpoint string API endpoint URL
-k, --insecure Skip TLS certificate verification
-p, --profile string Profile to use for configuration
--timeout string Request timeout duration
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-cli](../) - Expanso CLI - Command-line interface for Expanso
## Expanso Edge
## `expanso-edge`
Expanso Edge - Autonomous edge computing agent
### Synopsis
Expanso Edge is an autonomous edge computing agent that connects to the Expanso control plane
and executes data processing pipelines on your infrastructure.
#### What Is The Edge Agent?
The edge agent is a lightweight, autonomous service that:
• Connects securely to your managed Expanso control plane
• Registers with node identity and capabilities (labels, resources)
• Receives job assignments from the control plane
• Executes data processing pipelines assigned to the node
• Reports execution status and metrics back to the control plane
• Maintains itself with minimal human intervention
#### Getting Started:
1. Bootstrap your edge node (one-time setup):
expanso-edge bootstrap --token YOUR_BOOTSTRAP_TOKEN
2. Run the edge agent:
expanso-edge run
3. Verify from CLI that your node is connected:
expanso-cli node list
The edge agent will automatically reconnect if the connection is lost and will
execute jobs assigned by the control plane based on node selectors.
For complete guides, see the Getting Started section.
#### Environment:
EXPANSO_EDGE_API_LISTEN_ADDR (same as --api-listen)
EXPANSO_EDGE_BOOTSTRAP_FORCE_IPV4 Force IPv4 during bootstrap (same as --bootstrap-force-ipv4)
EXPANSO_EDGE_BOOTSTRAP_INSECURE Skip bootstrap TLS check (dev only) (same as --bootstrap-insecure)
EXPANSO_EDGE_BOOTSTRAP_NO_PROXY Bypass proxy during bootstrap (same as --bootstrap-no-proxy)
EXPANSO_EDGE_BOOTSTRAP_TOKEN Cloud bootstrap token (same as --bootstrap-token)
EXPANSO_EDGE_BOOTSTRAP_URL Bootstrap service URL (advanced) (same as --bootstrap-url)
EXPANSO_EDGE_DATA_DIR (same as --data-dir)
EXPANSO_EDGE_DNS_SERVERS Comma-separated DNS servers for the Go resolver
EXPANSO_EDGE_ENROLL_ORCHESTRATOR Orchestrator URL for v2 direct enrollment (same as --orchestrator)
EXPANSO_EDGE_ENROLL_TOKEN Enrollment token for v2 direct enrollment (same as --token)
EXPANSO_EDGE_LOCAL_MODE (same as --local)
EXPANSO_EDGE_LOG_FORMAT (same as --log-format)
EXPANSO_EDGE_LOG_LEVEL (same as --log-level)
EXPANSO_EDGE_NAME (same as --name)
EXPANSO_EDGE_NAME_PROVIDER (same as --name-provider)
EXPANSO_EDGE_STORE_POSTGRES_CONNECTION_STRING
EXPANSO_EDGE_STORE_POSTGRES_PASSWORD
EXPANSO_EDGE_TELEMETRY_AUTHENTICATION_TOKEN
EXPANSO_EDGE_TELEMETRY_ERROR_REPORTING_ENDPOINT
EXPANSO_EDGE_TELEMETRY_HEADERS_`` Map entry; set one variable per key
EXPANSO_PPROF_ADDR pprof/debug HTTP listen address
Prefer these over the equivalent flags for secrets: flag values are
visible in `ps` output and in /proc/``/cmdline on Linux.
### Options
```
-h, --help help for expanso-edge
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-edge bootstrap](bootstrap/) - Bootstrap your edge node to Expanso Cloud
* [expanso-edge config](config/) - Inspect how expanso-edge is configured
* [expanso-edge enroll](enroll/) - Enroll your edge node directly with an orchestrator
* [expanso-edge identity](identity/) - Inspect this edge node's local identity
* [expanso-edge run](run/) - Run the Expanso Edge agent
* [expanso-edge validate](validate/) - Validate pipeline configs locally
* [expanso-edge version](version/) - Show version information
## Bootstrap
## `expanso-edge bootstrap`
Bootstrap your edge node to Expanso Cloud
### Synopsis
Bootstrap your edge node to the Expanso control plane.
#### What Is Bootstrapping?
Bootstrapping is the one-time setup process where your edge node:
1. Contacts the Expanso bootstrap service using your bootstrap token
2. Authenticates and proves authorization to join the control plane
3. Receives unique node credentials and control plane connection details
4. Stores credentials locally in your data directory for future connections
This is a one-time setup. Once bootstrapped, your edge node will automatically
connect to the control plane when you run 'expanso-edge run'.
To enroll directly with an orchestrator (no Expanso Cloud hop), use
'expanso-edge enroll' with an orchestrator bootstrap token instead.
#### Where To Get Your Token:
1. Log into https://cloud.expanso.io
2. Navigate to Nodes → Add Node
3. Copy your bootstrap token (valid until it expires or is revoked)
#### What Happens After Bootstrap:
1. Node credentials are stored in your data directory
2. Run 'expanso-edge run' to start the agent
3. Node automatically connects and registers with the control plane
4. View your node: expanso-cli node list
5. Node is ready to receive job assignments
#### Security Notes:
• Bootstrap tokens are time-limited and can be revoked
• Node credentials are stored securely in your data directory
• Use --force to re-bootstrap (invalidates old credentials)
• Keep your data directory secure (contains node identity)
Examples:
# Bootstrap with token
expanso-edge bootstrap --token "abc123"
# Bootstrap with custom URL (self-hosted control plane)
expanso-edge bootstrap --token "abc123" --url "https://bootstrap.mycompany.com"
# Force re-bootstrap (get new credentials)
expanso-edge bootstrap --token "abc123" --force
```
expanso-edge bootstrap [flags]
```
### Options
```
-c, --config strings Paths to configuration files or directories
--data-dir string Data directory path
-f, --force Force re-bootstrap even if already bootstrapped
--force-ipv4 Force IPv4 for bootstrap requests (useful on networks with broken IPv6)
-h, --help help for bootstrap
-k, --insecure Skip TLS certificate verification
--no-proxy Disable HTTP proxy usage for bootstrap requests
-t, --token string Bootstrap token from Expanso Cloud. Env: EXPANSO_EDGE_BOOTSTRAP_TOKEN (preferred; flag values show in ps output)
-u, --url string Bootstrap service URL (advanced)
```
### Options inherited from parent commands
```
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-edge](../) - Expanso Edge - Autonomous edge computing agent
## Configuration
## `expanso-edge config`
Inspect how expanso-edge is configured
### Synopsis
Inspect how expanso-edge is configured.
#### Available Commands:
• env: list the environment variables the agent understands (with --json for a
machine-readable surface), including the bootstrap and enrollment tokens.
### Options
```
-h, --help help for config
```
### Options inherited from parent commands
```
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-edge](../) - Expanso Edge - Autonomous edge computing agent
* [expanso-edge config env](env.md) - List the environment variables expanso-edge understands
## Env
## `expanso-edge config env`
List the environment variables expanso-edge understands
### Synopsis
List the environment variables expanso-edge reads, with the equivalent flag and
config key for each and whether it carries a secret.
Prefer environment variables over flags for secrets (bootstrap and enrollment
tokens): a flag value is visible in `ps` output and in
/proc/``/cmdline on Linux. Use --json for a machine-readable surface.
```
expanso-edge config env [flags]
```
### Examples
```
# Human-readable listing
expanso-edge config env
# Machine-readable surface
expanso-edge config env --json
```
### Options
```
-h, --help help for env
--json Emit the environment surface as JSON
```
### Options inherited from parent commands
```
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-edge config](./) - Inspect how expanso-edge is configured
## Enroll
## `expanso-edge enroll`
Enroll your edge node directly with an orchestrator
### Synopsis
Enroll your edge node directly with an Expanso orchestrator.
This is the direct node enrollment path: the orchestrator validates the node's identity proof
and returns the connection details, which are persisted to your data directory.
The legacy cloud bootstrap flow is still supported, but it is not the recommended path for new deployments.
#### What Happens:
1. The agent generates (or loads) its local identity keypair (Ed25519).
2. It presents the proof as a credential to the orchestrator, which verifies it
against the trust anchor (bootstrap token, x509 CA, or OIDC issuer).
3. The orchestrator assigns a node ID, derives the workspace, and returns the
connection details, which are written to your data directory.
4. Run 'expanso-edge run' to connect.
#### Enrolling Without A Bootstrap Token:
Instead of a bootstrap token, enroll with a customer x509 certificate, an OIDC
JWT, an AWS instance identity document, an Azure IMDS attested document, or a
GCP instance identity token, validated against a trust anchor configured on the
orchestrator. No bootstrap token is needed.
x509_ca: select with --enrollment-source x509_ca and pass --source-id,
--cert, and --key (or set the 'enrollment.x509' config block).
oidc_issuer: config-driven (its provider settings have no flag surface). Set
'enrollment.oidc.provider' to one of: kubernetes (projected
service-account token file), client_credentials (OAuth2 token
endpoint), azure (IMDS managed identity), or gcp (instance
identity token). For client_credentials the client secret is read
from the env var named by 'client_secret_env' -- never from config.
aws_iid: select with --enrollment-source aws_iid and pass --source-id (run
on an EC2 instance). The instance identity document is fetched from
IMDS automatically; the optional 'enrollment.aws_iid' config block
only tunes IMDS (allow_imdsv1, token_ttl_seconds, endpoint,
document_path).
aws_iam: select with --enrollment-source aws_iam and pass --source-id (run
with an IAM role -- e.g. an ECS Fargate task role, which has no EC2
instance identity document). A signed sts:GetCallerIdentity request
is built from the task-role credentials; the 'enrollment.aws_iam'
config block supplies the required 'server_id' (matching the trust
anchor) plus optional 'region', 'sts_endpoint', and 'profile'.
azure_msi: select with --enrollment-source azure_msi and pass --source-id (run
on an Azure VM). The IMDS attested document is fetched automatically;
the optional 'enrollment.azure_msi' config block only tunes IMDS
(api_version, nonce, endpoint).
gcp_iit: select with --enrollment-source gcp_iit and pass --source-id (run
on a GCE instance). The instance identity token is fetched from the
metadata server automatically; the 'enrollment.gcp_iit' config block
supplies the required 'audience' (matching the trust anchor) plus an
optional 'endpoint' override.
Examples:
# Enroll with a new orchestrator-only bootstrap token
expanso-edge enroll --token exp_obk_... --orchestrator https://orch.example.com
# Force re-enroll (mint a fresh token first)
expanso-edge enroll --token exp_obk_... --orchestrator https://orch.example.com --force
# Enroll with a customer x509 certificate
expanso-edge enroll --enrollment-source x509_ca --source-id `` \
--cert /etc/expanso/identity/cert.pem --key /etc/expanso/identity/key.pem \
--orchestrator https://orch.example.com
# Enroll with OIDC (config-driven -- providers have no flag surface):
# enrollment:
# source_type: oidc_issuer
# source_id: ``
# oidc:
# provider: kubernetes
# token_path: /var/run/secrets/tokens/expanso
expanso-edge enroll --orchestrator https://orch.example.com --config /etc/expanso/edge.yaml
# Enroll with an AWS instance identity document (run on an EC2 instance)
expanso-edge enroll --enrollment-source aws_iid --source-id `` \
--orchestrator https://orch.example.com
# Enroll with an AWS IAM role via sts:GetCallerIdentity (e.g. ECS Fargate;
# set enrollment.aws_iam.server_id in config to match the trust anchor)
expanso-edge enroll --enrollment-source aws_iam --source-id `` \
--orchestrator https://orch.example.com
# Enroll with an Azure IMDS attested document (run on an Azure VM)
expanso-edge enroll --enrollment-source azure_msi --source-id `` \
--orchestrator https://orch.example.com
# Enroll with a GCP instance identity token (run on a GCE instance;
# set enrollment.gcp_iit.audience in config to match the trust anchor)
expanso-edge enroll --enrollment-source gcp_iit --source-id `` \
--orchestrator https://orch.example.com
```
expanso-edge enroll [flags]
```
### Options
```
--cert string x509_ca: PEM cert chain path (overrides config)
-c, --config strings Paths to configuration files or directories
--data-dir string Data directory path
--enrollment-source string Enrollment source type: bootstrap_token (default), x509_ca, oidc_issuer, aws_iid, aws_iam, azure_msi, or gcp_iit
-f, --force Re-attempt enrollment even if local config shows the node is already enrolled (identity is bound to the keypair; an existing node returns its existing identity)
-h, --help help for enroll
-k, --insecure Skip TLS certificate verification
--key string x509_ca: PEM private key path (overrides config)
-o, --orchestrator string Orchestrator base URL
--source-id string Trust-anchor id (required for every source except bootstrap_token)
-t, --token string Bootstrap token (exp_obk_...); for the bootstrap_token source. Env: EXPANSO_EDGE_ENROLL_TOKEN (preferred; flag values show in ps output)
```
### Options inherited from parent commands
```
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-edge](../) - Expanso Edge - Autonomous edge computing agent
## Identity
## `expanso-edge identity`
Inspect this edge node's local identity
### Synopsis
Inspect the cryptographic identity material this edge node holds.
The agent generates an Ed25519 keypair on its first boot and persists the
private key under the configured data directory. Subcommands here read that
material for operator inspection — the private key never leaves the device.
### Options
```
-h, --help help for identity
```
### Options inherited from parent commands
```
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-edge](../) - Expanso Edge - Autonomous edge computing agent
* [expanso-edge identity show](show.md) - Print this node's public key
## Show
## `expanso-edge identity show`
Print this node's public key
### Synopsis
Print this edge node's locally-generated Ed25519 public key in
lowercase hex (64 characters, no trailing newline written to stdout).
The key is read from the file at `${data_dir}/identity/key`. If no key is
present, run `expanso-edge bootstrap` first to generate one.
```
expanso-edge identity show [flags]
```
### Options
```
-c, --config strings Paths to configuration files or directories
--data-dir string Data directory path
-h, --help help for show
```
### Options inherited from parent commands
```
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-edge identity](./) - Inspect this edge node's local identity
## Run
## `expanso-edge run`
Run the Expanso Edge agent
### Synopsis
Run the Expanso Edge agent to connect to the control plane and execute jobs.
#### What Happens When You Run:
1. Agent loads configuration and credentials (from bootstrap)
2. Connects to the Expanso control plane
3. Registers node with capabilities and labels
4. Begins listening for job assignments
5. Executes jobs that match the node's selector labels
6. Reports execution status and metrics back to the control plane
The agent runs continuously, maintaining connection and executing assigned jobs.
#### Configuration Reloading:
By default, the agent monitors configuration files and automatically restarts
when changes are detected. This allows you to update node labels, resources,
or other settings without manual restarts.
Use --no-watch to disable automatic reloading (useful in containerized environments).
#### Modes:
• Standard mode (default): Connects to control plane using bootstrap credentials
• Local mode (--local): Runs standalone without control plane (testing/development)
#### Monitoring:
Once running, verify your node is connected:
expanso-cli node list # See all nodes
expanso-cli node describe NODE_ID # View node details
expanso-cli execution list --node NODE_ID # See jobs running on node
#### Prerequisites:
Before running, you must bootstrap your node:
expanso-edge bootstrap --token YOUR_BOOTSTRAP_TOKEN
Examples:
# Run with config watching (standard)
expanso-edge run
# Run without config watching
expanso-edge run --no-watch
# Run in local mode (no control plane connection)
expanso-edge run --local
# Run with custom config file
expanso-edge run --config /path/to/config.yaml
# Run with verbose logging
expanso-edge run --verbose
```
expanso-edge run [flags]
```
### Options
```
--api-listen string API listen address
--bootstrap-force-ipv4 Force IPv4 for bootstrap requests (useful on networks with broken IPv6)
-k, --bootstrap-insecure Skip TLS certificate verification for bootstrap
--bootstrap-no-proxy Disable HTTP proxy usage for bootstrap requests
--bootstrap-token string Bootstrap token from Expanso Cloud. Env: EXPANSO_EDGE_BOOTSTRAP_TOKEN (preferred; flag values show in ps output)
--bootstrap-url string Bootstrap service URL (advanced)
-c, --config strings Paths to configuration files or directories
--data-dir string Data directory path
-h, --help help for run
--local Run in local mode (no control plane connection)
--log-format string Log format (json, text, console)
--log-level string Log level (trace, debug, info, warn, error)
--name string Node name (defaults to hostname)
--name-provider string Name provider for auto-generation: cloud, hostname, uuid, machine-id (default: hostname)
--no-watch Disable configuration file watching
--orchestrator string Orchestrator URL for v2 direct enrollment
--restart-delay duration Delay before restarting service on config change (default 2s)
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-edge](../) - Expanso Edge - Autonomous edge computing agent
## Validate
## `expanso-edge validate`
Validate pipeline configs locally
### Synopsis
Validate one or more pipeline configs offline, without contacting an
orchestrator.
Input is read from the given FILE paths, or from stdin when no file is given or
the path is "-". A file may contain multiple YAML documents separated by "---";
each is validated independently. Each document is auto-detected:
- A bare pipeline config (top-level "input"/"output") is fully validated
(config schema, mapping expressions, and component types).
- A job spec (has a "config" block) is NOT validated as a job spec -- it is
only parsed structurally to reach the pipeline config it carries. The spec
just has to be well-formed YAML/JSON that parses as a job; its job-level
fields are ignored. For a pipeline job the embedded config IS fully
validated (a pipeline job with no config is an error).
This validates pipeline config syntax and structure only. It does NOT validate
the job spec itself: job-level fields (name, type, selectors, rollout, restart
policy) are not checked, and it does not run the orchestrator's submission
validation or any server dry-run -- a config that passes here can still be
rejected at submission.
```
expanso-edge validate [FILE...] [flags]
```
### Examples
```
# Validate a config file
expanso-edge validate pipeline.yaml
# Validate a piped config
cat pipeline.yaml | expanso-edge validate -
# Validate several files with JSON output
expanso-edge validate a.yaml b.yaml --output json
```
### Options
```
-h, --help help for validate
-o, --output {text|json} Output format (default text)
```
### Options inherited from parent commands
```
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-edge](../) - Expanso Edge - Autonomous edge computing agent
## Version
## `expanso-edge version`
Show version information
```
expanso-edge version [flags]
```
### Options
```
-d, --detailed Show detailed version information
-f, --format {text|json|yaml} Output format (default text)
-h, --help help for version
```
### Options inherited from parent commands
```
-v, --verbose Enable verbose logging
```
### SEE ALSO
* [expanso-edge](../) - Expanso Edge - Autonomous edge computing agent
## edge-config
# Edge Configuration Reference
This page documents all available configuration options for the Expanso Edge agent.
## Configuration File
The edge configuration file is typically located at `/etc/expanso/edge/config.yaml` or can be specified via the `--config` flag.
## Configuration Options
All configuration options are optional and have sensible defaults. You only need to specify what you want to change.
| Field | Type | Description |
|-------|------|-------------|
| `name` | `string` | Name is the node name that identifies this edge node in the control plane. |
| `name_provider` | `string` | NameProvider controls automatic name generation when name is not explicitly set. |
| `data_dir` | `string` | DataDir is the core data directory where all edge state is stored. |
| `local_mode` | `bool` | LocalMode enables standalone operation without control plane connection. |
| `orchestrator` | `*EdgeOrchestratorConfig` | Orchestrator contains connection settings for the Expanso control plane. |
| `enrollment` | `*EdgeEnrollmentConfig` | Enrollment selects how `expanso-edge enroll` proves the node's identity. |
| `api` | `APIConfig` | - |
| `log` | `LogConfig` | - |
| `telemetry` | `telemetry.Config` | - |
| `store` | `StoreConfig` | - |
| `shutdown_timeout` | `time.Duration` | ShutdownTimeout is the maximum time to wait for graceful shutdown. |
| `hardware_fingerprint` | `string` | HardwareFingerprint is a platform-injected override for the auto-detected machine ID. |
| `labels` | `map[string]string` | Labels are key-value pairs used for node selection and job targeting. |
| `secrets` | `SecretsConfig` | Secrets contains configuration for the secrets subsystem. |
| `executor` | `ExecutorConfig` | Executor contains configuration for job executors. |
| `lineage` | `LineageConfig` | Lineage configures OpenLineage event emission at pipeline lifecycle |
| `pipeline_metrics` | `EdgePipelineMetricsConfig` | PipelineMetrics configures publishing a curated per-pipeline metrics |
## Nested Configuration
### Orchestrator Configuration (`orchestrator`)
**Important**: This section is automatically populated when you run `expanso-edge bootstrap`. You should not manually configure these settings.
The bootstrap process connects to the Expanso orchestrator, obtains authentication credentials, and saves them to `config.d/99-dynamic.yaml`. These settings are managed automatically.
| Field | Type | Description |
|-------|------|-------------|
| `node_id` | `string` | Node ID assigned during bootstrap (auto-populated) |
| `credentials_path` | `string` | Path to NATS credentials file (auto-populated) |
| `address` | `string` | Orchestrator NATS address (auto-populated) |
| `refresh_address` | `string` | Orchestrator refresh endpoint (auto-populated) |
| `require_tls` | `bool` | Require TLS for connections |
| `insecure` | `bool` | Enable insecure mode (development only) |
| `heartbeat_interval` | `duration` | Interval for sending heartbeats (can override default) |
### API Configuration (`api`)
Configuration for the Edge API server.
| Field | Type | Description |
|-------|------|-------------|
| `listen_addr` | `string` | API listen address (e.g., `localhost:9010`) |
| `auth.token` | `string` | API authentication token |
### Log Configuration (`log`)
Configuration for logging.
| Field | Type | Description |
|-------|------|-------------|
| `level` | `string` | Log level: `trace`, `debug`, `info`, `warn`, `error` |
| `format` | `string` | Log format: `console`, `json`, `text` |
### Telemetry Configuration (`telemetry`)
Configuration for metrics and telemetry export.
| Field | Type | Description |
|-------|------|-------------|
| `do_not_track` | `bool` | Disable telemetry collection |
| `endpoint` | `string` | Telemetry collector endpoint |
| `endpoint_path` | `string` | Path for telemetry endpoint |
| `protocol` | `string` | Export protocol: `grpc` or `http` |
| `insecure` | `bool` | Disable TLS verification |
| `export_interval` | `duration` | How often to export metrics (default: 60s) |
| `headers` | `map[string]string` | Optional headers for authentication |
| `resource_attributes` | `map[string]string` | Additional resource attributes |
| `drop_metric_prefixes` | `[]string` | Metric name prefixes to drop entirely |
| `drop_metric_attributes` | `map[string][]string` | Attribute keys to strip per metric name (name may end in `*`), collapsing the series they fan out into |
| `include_go_metrics` | `bool` | Include Go runtime metrics |
| `process_metrics_interval` | `duration` | Process metrics collection interval (default: 60s) |
| `authentication.type` | `string` | Authentication type (e.g., `Basic`) |
| `authentication.token` | `string` | Authentication token |
| `authentication.namespace` | `string` | Telemetry namespace |
## Detailed Configuration Guide
This section provides in-depth guidance for key configuration options.
### `name`
**Type:** `string`
Name is the node name that identifies this edge node in the control plane.
WHEN TO SET:
- Explicitly set for meaningful identification (e.g., "warehouse-scanner-01")
- Leave empty to auto-generate based on name_provider
DEFAULT: Auto-generated using name_provider (default: hostname)
IMPACT:
- Human-readable display name used in UI and CLI
- Users can list and query nodes by name (queries fail if duplicate names exist)
- Optional field - separate from the auto-generated NodeID
### `name_provider`
**Type:** `string`
NameProvider controls automatic name generation when name is not explicitly set.
Valid values: "cloud", "hostname", "uuid", "machine-id"
WHEN TO USE EACH:
- "hostname" (default): Use system hostname - good for VMs with meaningful hostnames
- "uuid": Generate random UUID - good for containers/temporary nodes
- "machine-id": Use system machine-id - good for persistent physical hardware
- "cloud": Use cloud provider instance ID - good for AWS/GCP/Azure deployments
DEFAULT: "hostname"
IMPACT:
Only used if name field is empty. Once name is set (manually or auto-generated),
it persists and name_provider is no longer used.
### `data_dir`
**Type:** `string`
DataDir is the core data directory where all edge state is stored.
Subdirectories are managed automatically: state/, metrics/, temp/, auth/, config.d/
WHEN TO SET:
- Production: Use persistent storage location (e.g., /var/lib/expanso-edge)
- Development: Use local directory (e.g., ./data)
- Containers: Use mounted volume (e.g., /data)
REQUIRED: Yes
SECURITY:
This directory contains node credentials and sensitive data. Ensure:
- Proper file permissions (600/700)
- Persistent storage (survives restarts)
- Regular backups for disaster recovery
- Not in world-readable location
IMPACT:
If this directory is lost, node must be re-bootstrapped with new credentials.
### `local_mode`
**Type:** `bool`
LocalMode enables standalone operation without control plane connection.
WHEN TO USE TRUE:
- Development and testing without control plane
- Air-gapped environments with no network access
- Standalone edge computing scenarios
- Running edge independently for demos/evaluation
WHEN TO USE FALSE (default):
- Production deployments with centralized management
- Scenarios requiring job orchestration from central control plane
- When you need remote monitoring and management
IMPACT WHEN TRUE:
- No control plane connection (orchestrator section ignored)
- No remote job assignments
- Node runs independently
- API remains available for local management
IMPACT WHEN FALSE:
- Requires bootstrap credentials or existing connection
- Connects to control plane for job assignments
- Enables centralized management and monitoring
DEFAULT: false (control plane mode)
### `shutdown_timeout`
**Type:** `time.Duration`
ShutdownTimeout is the maximum time to wait for graceful shutdown.
WHEN TO ADJUST:
- Increase for long-running job cleanup (e.g., 60s, 120s)
- Decrease for fast restarts in development (e.g., 10s)
DEFAULT: 30s
IMPACT:
- Jobs are given this time to complete gracefully
- After timeout, edge forcefully terminates
- Too short: jobs may not cleanup properly
- Too long: slow restarts and deployments
### `labels`
**Type:** `map[string]string`
Labels are key-value pairs used for node selection and job targeting.
COMMON USE CASES:
- Environment: env=production, env=staging
- Location: region=us-west, datacenter=dc1, zone=a
- Hardware: gpu=nvidia-t4, cpu=high-performance
- Function: role=log-processor, type=edge-gateway
HOW JOBS USE LABELS:
Jobs specify selectors to match nodes:
selector:
match_labels:
env: production
region: us-west
BEST PRACTICES:
- Use consistent naming (lowercase, hyphens)
- Keep labels stable (don't change frequently)
- Document label schema across your fleet
- Use hierarchical labels (region/zone, env/tier)
DYNAMIC UPDATES:
Labels can be updated without restart if config watching is enabled.
New jobs will target based on updated labels immediately.
## Scenario-Based Examples
### Production Deployment
Minimal configuration for production edge nodes. The orchestrator connection is established automatically via `expanso-edge bootstrap`.
```yaml
# Node identification (optional - defaults to hostname)
name: "" # Leave empty to auto-generate from hostname
name_provider: hostname
# Data storage
data_dir: /var/lib/expanso/edge
# Labels for job targeting
labels:
env: production
region: us-west
role: log-processor
# Optional overrides
log:
level: info
format: json
shutdown_timeout: 60s # Allow jobs time to cleanup
```
**Note**: After running `expanso-edge bootstrap`, orchestrator connection settings are automatically saved to `config.d/99-dynamic.yaml`.
### Development/Testing
Configuration for local development in standalone mode (no orchestrator connection):
```yaml
name: dev-edge
data_dir: ./data
local_mode: true # Standalone mode - no orchestrator connection
log:
level: debug
format: console
telemetry:
do_not_track: true # Disable telemetry
shutdown_timeout: 10s # Fast restarts
```
### Container Deployment
Configuration for containerized environments:
```yaml
name_provider: uuid # Generate unique ID for each container
data_dir: /data # Mounted volume
labels:
env: ${ENV} # From environment variables
pod: ${HOSTNAME}
log:
level: info
format: json # Structured logs for aggregation
```
## Minimal Example
The simplest possible configuration - everything else uses defaults:
```yaml
data_dir: /var/lib/expanso/edge
```
This is all you need! The edge agent will:
- Auto-generate a name from the hostname
- Use default log settings (info level, console format)
- Listen on the default API address (localhost:9010)
- After running `expanso-edge bootstrap`, connect to the orchestrator automatically
## Platform Support
# Platform Support
Each Expanso Edge release includes the `expanso-edge` agent and the `expanso-cli`
command-line tool for the platforms below. To install them, see
[Installation](/getting-started/installation).
## Binaries
| Operating system | Architectures |
|---|---|
| Linux | `amd64` (x86-64), `arm64`, `armv7` (32-bit ARM) |
| macOS | `amd64` (Intel), `arm64` (Apple silicon) |
| Windows | `amd64`, `arm64` |
- **Linux:** The Linux binaries are statically linked, so they do not need a
specific C library (glibc or musl). On a 64-bit ARM operating system, use
`arm64`. Use `armv7` only on a 32-bit ARM operating system.
- **macOS:** Current releases require macOS 12 Monterey or later.
- **Windows:** Current releases support Windows 10 or Windows Server 2016 or
later. You can also run the Linux build in WSL2 (Windows Subsystem for Linux).
## Container Images
| Image | Architectures |
|---|---|
| `ghcr.io/expanso-io/expanso-edge` | `linux/amd64`, `linux/arm64`, `linux/arm/v7` |
| `ghcr.io/expanso-io/expanso-cli` | `linux/amd64`, `linux/arm64`, `linux/arm/v7` |
Docker selects the correct architecture for your host automatically.
The images use Alpine Linux as the base image. The process in the container runs
as the non-root user `expanso`.
For the Red Hat certified image, see
[Red Hat Enterprise Linux and OpenShift](#red-hat-enterprise-linux-and-openshift).
## Red Hat Enterprise Linux and OpenShift
Expanso Edge is Red Hat certified.
### RHEL 9.x / 10.x
- **Architectures:** x86_64 (amd64), ARM64
- **Status:** Red Hat Certified
- **Container base:** UBI9
- **Image:** `registry.connect.redhat.com/expanso/expanso-edge`
### OpenShift 4.x
- **Versions:** 4.11 and later
- **Variants:** OCP, ROSA, ARO, RHOIC, Dedicated, SNO, Local
- **Status:** Red Hat Certified
- **Install:** the `expanso-edge` Helm chart in the Red Hat certified chart
repository ([charts.openshift.io](https://charts.openshift.io/))
## Kubernetes
- **Upstream Kubernetes:** 1.24 and later
- **Managed Services:** EKS, GKE, AKS, IKS, OKE, and more
- **Distributions:** OpenShift, Rancher, K3s, MicroK8s, Kind, Minikube
## Container Runtimes
- ✅ **Docker**
- ✅ **Podman** 4.0+
- ✅ **CRI-O** 1.24+ (OpenShift default)
- ✅ **containerd** 1.6+
## Cloud Platforms
All major cloud providers supported:
- ✅ **AWS** - EC2, EKS, ROSA (x86_64, Graviton ARM64)
- ✅ **Google Cloud** - Compute Engine, GKE, Tau T2A ARM64
- ✅ **Microsoft Azure** - VMs, AKS, ARO (x86_64, ARM64)
- ✅ **IBM Cloud** - Virtual Servers, IKS, RHOIC
- ✅ **Oracle Cloud** - Compute, OKE, Ampere A1 ARM64
- ✅ **Alibaba Cloud** - ECS, ACK
## Edge & IoT Hardware
Compatible with any device supporting the target OS and architecture:
- Raspberry Pi 2 and later, including Raspberry Pi Zero 2 W
- NVIDIA Jetson (Nano, Xavier, Orin)
- Intel NUC, UP Board
- Dell, Advantech, Siemens, HPE edge gateways
- Custom arm64, armv7 or x86-64 embedded systems
## Air-Gapped Environments
Nodes that Expanso Cloud manages must be able to reach Expanso Cloud. To run in a
network with no internet access, you need a private control plane, which is
available to enterprise customers. Contact
[support@expanso.io](mailto:support@expanso.io).
To run a single node with no connection, use
[Local Mode](/getting-started/local-mode). Local mode has no fleet
management or central control.
## Certification
- ✅ Red Hat Certified (container & Helm chart)
- ✅ Security scanned (Quay.io Clair)
- ✅ UBI9-based Red Hat certified image
## Other Platforms
Releases do not include other operating systems or architectures, for example
FreeBSD or 32-bit x86. To ask about a platform that is not on this page, contact
[support@expanso.io](mailto:support@expanso.io).
## Need Help?
- **Custom platform builds:** [Ask Us!](mailto:support@expanso.io?subject=Platform%20Support)
- **Community support:** [Join Slack](https://exso.cloud/slack)
- **Professional support:** [support@expanso.io](mailto:support@expanso.io)
## Full Reference
See https://docs.expanso.io/references for complete documentation.