CLI Reference

Complete reference for the Expanse command-line interface.

Global Flags

Flag	Description
`--config`	Path to config file (default: `$HOME/.expanse.yaml`)

Project Commands

expanse init

Initialise a new Expanse project.

expanse init [project-name]

Creates a project directory with an expanse.yaml containing your globally configured clusters. If no name is given, prompts interactively.

Examples:

expanse init                          # Interactive mode
expanse init my-simulation            # Create project named "my-simulation"

expanse run

Run a node or workflow.

expanse run <target> [flags]

Flag	Short	Default	Description
`--cluster`	`-c`	`"local"`	Execution cluster
`--no-cache`	-	`false`	Skip build cache and force fresh builds
`--quiet`	`-q`	`false`	Compact single-line progress
`--verbose`	`-v`	`false`	Show detailed progress including file transfers
`--no-preflight`	-	`false`	Skip preflight builds; build during execution instead
`--skip-validation`	-	`false`	Skip pre-run configuration validation

Examples:

expanse run solver                    # Run a node
expanse run simple-pipeline           # Run a workflow by name
expanse run workflows/pipeline.yaml   # Run a workflow by path
expanse run solver --cluster archer2  # Target a specific cluster
expanse run solver --no-cache         # Force fresh builds
expanse run solver -v                 # Verbose output

expanse validate

Validate project, workflow, or node configuration.

expanse validate [target]

Without arguments, validates the entire project in the current directory. With a target, validates that specific workflow or node and its references.

Examples:

expanse validate                      # Validate entire project
expanse validate nodes/solver         # Validate a specific node
expanse validate workflows/pipeline.yaml  # Validate a specific workflow

Job Commands

expanse jobs

List recent jobs.

expanse jobs [flags]

Flag	Short	Default	Description
`--status`	-	-	Filter by status (`pending`, `running`, `completed`, `failed`, `cancelled`)
`--last`	`-n`	`10`	Number of jobs to show

Examples:

expanse jobs                          # List 10 most recent jobs
expanse jobs --status running         # Show only running jobs
expanse jobs -n 20                    # Show last 20 jobs

expanse status

Show status for a job or all jobs for a target.

expanse status <job-id | target>

The target can be a job ID, path, or name that will be searched in the nodes/ and workflows/ directories.

Examples:

expanse status job-1234567890         # Status of a specific job
expanse status train                  # All jobs for the "train" node
expanse status ./nodes/solver         # All jobs for a node by path

expanse logs

Stream logs for a job.

expanse logs <job-id> [flags]

Flag	Short	Default	Description
`--follow`	`-f`	`true`	Follow log output (like `tail -f`)

Examples:

expanse logs job-1234567890           # Stream logs (follows by default)
expanse logs job-1234567890 -f=false  # Print current logs and exit

expanse cancel

Cancel a running job.

expanse cancel <job-id> [flags]

Flag	Default	Description
`--force`	`false`	Force kill the job

Examples:

expanse cancel job-1234567890         # Cancel gracefully
expanse cancel job-1234567890 --force # Force kill

expanse reconnect

Re-attach to a running job and stream its logs. Useful after a daemon restart when you want to resume monitoring a job that is still running on the cluster.

expanse reconnect <job-id>

The job must be in running or needs_reconcile status. For completed jobs, use expanse logs instead.

Cluster Commands

expanse cluster setup

Interactive wizard to configure computing clusters globally. This is a one-time step: configured clusters are available in every project you create.

expanse cluster setup [flags]

Flag	Description
`--debug`	Enable debug logging for SSH connections

The wizard:

Configures a local cluster automatically
Scans your ~/.ssh/config for known HPC hosts
Lets you add additional clusters manually
Asks you to select a default cluster

Configuration is saved to ~/.expanse/global-clusters.yaml.

expanse cluster add

Add a new cluster to the global configuration.

expanse cluster add [cluster-name]

If no name is given, runs the interactive wizard. The wizard guides you through selecting a cluster type, entering connection details, and verifying the connection.

Examples:

expanse cluster add                   # Interactive wizard
expanse cluster add my-hpc            # Provide name upfront

expanse cluster list

List all configured clusters.

expanse cluster list

expanse cluster remove

Remove a cluster from the global configuration. Does not affect existing projects that already reference this cluster.

expanse cluster remove <cluster-name>

Authentication Commands

Authenticate with Expanse using OAuth device flow. Opens a browser window for login. Credentials are stored securely in your system keychain.

expanse login [flags]

Flag	Short	Default	Description
`--force`	`-f`	`false`	Force re-authentication even if already logged in

expanse logout

Clear stored Expanse credentials.

expanse logout

expanse auth status

Display Expanse and Globus authentication status.

expanse auth status

expanse whoami

Show the currently authenticated user.

expanse whoami

Authenticate with Globus for cross-cluster data transfers. This is a one-time setup required only if your clusters use Globus endpoints.

expanse auth globus login

expanse auth globus logout

Clear stored Globus credentials.

expanse auth globus logout

expanse auth globus status

Show Globus authentication status.

expanse auth globus status

Configuration Commands

expanse config get

Get a configuration value from the project’s expanse.yaml. Supports dot-notation for nested keys.

expanse config get <key>

Examples:

expanse config get defaults.cluster   # Show the default cluster
expanse config get project.name       # Show the project name

expanse config set

Set a configuration value in the project’s expanse.yaml. Supports dot-notation for nested keys.

expanse config set <key> <value>

Examples:

expanse config set defaults.cluster my-hpc   # Change default cluster
expanse config set project.version 2.0       # Update project version
expanse config set agent.provider anthropic   # Set agent AI provider
expanse config set agent.model claude-sonnet-4-5-20250929  # Set agent model
expanse config set agent.theme dark           # Set agent UI theme

expanse config import

Import cluster configuration from a file.

expanse config import <path>

Intelligence Commands

expanse predict

Get AI-powered resource recommendations for a node.

expanse predict <target> [flags]

Flag	Short	Default	Description
`--cluster`	`-c`	project default	Target cluster for the prediction

Examples:

expanse predict solver                        # Predict resources for a node
expanse predict solver --cluster archer2      # Predict for a specific cluster

expanse agent

Launch an interactive AI assistant that can inspect jobs, analyse code, query clusters, and run workflows.

expanse agent [flags]

Flag	Short	Description
`--prompt`	`-p`	Send a single prompt and exit (non-interactive mode)
`--session`	`-s`	Resume a previous session (omit ID to resume the last session)

Subcommands:

Subcommand	Description
`expanse agent install`	Install the agent and its dependencies
`expanse agent uninstall`	Remove the agent and its dependencies

Examples:

expanse agent                                 # Interactive session
expanse agent --prompt "Why did my last job fail?"  # Single prompt
expanse agent -s                              # Resume last session
expanse agent -s abc123                       # Resume specific session
expanse agent install                         # Install agent dependencies
expanse agent uninstall                       # Remove agent dependencies

See Expanse Intelligence for full details.

Registry Commands

expanse add

Add a node from the registry to your project.

expanse add <node[@version]> [flags]

Flag	Short	Default	Description
`--mode`	`-m`	`"reference"`	Add mode: `reference` or `submodule`
`--configure`	-	`false`	Interactively configure node parameters

Examples:

expanse add my-solver                 # Add latest version as reference
expanse add my-solver@1.0.0           # Add specific version
expanse add my-solver --mode submodule  # Clone as git submodule
expanse add my-solver --configure     # Interactive parameter setup

expanse node publish

Publish the current directory as a node to the registry. Reads node.yaml from the current directory and uses git to determine the repository URL and current commit SHA.

expanse node publish [flags]

Flag	Short	Description
`--version`	`-v`	Version to publish (overrides `node.yaml`)
`--description`	`-d`	Description text
`--tags`	`-t`	Comma-separated tags
`--license`	`-l`	Licence identifier
`--homepage`	-	Homepage URL
`--submodule`	-	Allow adding as git submodule (default: `true`)

Examples:

expanse node publish
expanse node publish --version 1.0.0 --tags "cfd,solver"

expanse node search

Search for nodes in the registry.

expanse node search [query] [flags]

Flag	Short	Default	Description
`--tag`	`-t`	-	Filter by tag
`--limit`	`-n`	`20`	Maximum results to return

Examples:

expanse node search mesh              # Search by keyword
expanse node search --tag cfd         # Filter by tag
expanse node search solver -n 50      # Show up to 50 results

expanse node info

View details about a registry node.

expanse node info <name> [flags]

Flag	Short	Description
`--version`	`-v`	Show a specific version

Examples:

expanse node info my-solver
expanse node info my-solver --version 1.0.0

expanse node delete

Delete a node and all its versions from the registry. Only the owner can delete a node. This action cannot be undone.

expanse node delete <name> [flags]

Flag	Short	Description
`--force`	`-f`	Skip confirmation prompt

Plugin Commands

expanse plugins list

List available solver plugins.

expanse plugins list

expanse plugins add

Add a solver node configuration to a workflow. Creates a node YAML file with the plugin’s example configuration.

expanse plugins add <plugin> [workflow-path] [flags]

Flag	Short	Description
`--name`	`-n`	Custom node name (defaults to plugin name)
`--print`	`-p`	Print to stdout instead of creating a file

Examples:

expanse plugins add fluent                    # Creates ./nodes/fluent.yaml
expanse plugins add fluent ./my-workflow      # Creates ./my-workflow/nodes/fluent.yaml
expanse plugins add fluent --name cfd-solver  # Creates ./nodes/cfd-solver.yaml
expanse plugins add fluent --print            # Print config to stdout

expanse plugins validate

Validate a solver node configuration file using plugin-specific validation.

expanse plugins validate <path>

Daemon Commands

expanse daemon

Manage the Expanse daemon.

expanse daemon start      # Start the daemon
expanse daemon stop       # Stop the daemon
expanse daemon status     # Check daemon status (PID, version, uptime)
expanse daemon restart    # Restart the daemon
expanse daemon install    # Download and install the daemon binary
expanse daemon uninstall  # Remove the daemon binary

The install subcommand downloads the daemon binary for your platform, verifies its SHA256 checksum, and installs it. If the daemon is not installed when you run a command that requires it, the CLI will prompt you to install it automatically.

Utility Commands

expanse version

Print the CLI version.

expanse version

expanse completion

Generate shell autocompletion scripts.

expanse completion bash     # Bash completion
expanse completion zsh      # Zsh completion
expanse completion fish     # Fish completion

To enable autocompletion, follow the instructions printed by the command for your shell.

Previous ← Integrations Next Glossary →