CLI

Install, update, and use the Dedalus CLI for Dedalus Cloud Services (DCS).

The Dedalus command-line interface (CLI) lets people, scripts, and agents create and control Dedalus Machines, persistent Linux virtual machines (VMs), without interfacing with a dashboard. The CLI allows you to control their lifecycle, run commands, open interactive SSH sessions, expose services, retrieve files, and inspect usage.

Install

Homebrew

brew install dedalus-labs/tap/dedalus

Homebrew installs the version currently published in the tap. Compare dedalus --version with the latest CLI release; if the tap trails the release, use Go, curl, or PowerShell.

Verify the installation and inspect the available commands:

dedalus --version
dedalus --help

Authenticate

Commands that call the Dedalus API need an API key. Create one in the Dedalus Dashboard, then export it in your shell:

export DEDALUS_API_KEY="your-api-key"

Prefer the environment variable to --api-key in scripts. This keeps the key out of shell history and command arguments.

To verify that the CLI can access your account, run the following command to list your machines:

dedalus machines list

Update

Update the current installation, or check for a newer release without installing it:

dedalus update
dedalus update --check

Homebrew and curl-installer installations update in place. On Windows, the command prints the PowerShell update command. Go users should rerun go install github.com/dedalus-labs/dedalus-cli/cmd/dedalus@latest.

During interactive use, the CLI periodically checks for a newer release and asks before updating. Continuous integration jobs and commands without an interactive terminal skip this check. Set DEDALUS_NO_UPDATE_CHECK=1 to disable it in interactive shells.

If an older CLI does not recognize dedalus update, reinstall it with the Go, curl, or PowerShell command above.

How commands are organized

Each command names a resource, an action, and any input needed for that action. A resource is an object managed by Dedalus, such as a Machine or execution.

dedalus <resource> <action> [flags]
dedalus machines <subresource> <action> [flags]

machines is the main resource. Nested resources belong to one Machine, so their commands also require --machine-id. Examples of subresources include executions and artifacts. An execution is a command run inside a Machine, and an artifact is a file captured from an execution.

Required request-body values can come from flags or JSON or YAML sent through standard input. Resource identifiers such as --machine-id remain command flags.

Command index

Global flags

Global flags apply to every command. Use them to authenticate, select the API endpoint, and control how the CLI prints results.

Flag	What it controls
--api-key	Sends an API key in the Authorization header. Prefer the DEDALUS_API_KEY environment variable so the key does not appear in shell history.
--x-api-key	Sends the DEDALUS_X_API_KEY value in the x-api-key header.
--dedalus-org-id	Optional. Leave unset for ordinary API-key setup: the key identifies its organization. Also accepts DEDALUS_ORG_ID. If supplied, it must match the key’s organization.
--base-url	Sends API requests to a different base URL.
--format	Formats successful output as auto, explore, json, jsonl, pretty, raw, or yaml.
--format-error	Applies the same format choices to error output.
--transform	Selects or reshapes successful JSON output with a GJSON expression.
--transform-error	Selects or reshapes JSON error output with a GJSON expression.
--raw-output, -r	Prints a transformed string without JSON quotes.
--debug	Prints HTTP request and response details for troubleshooting.

Machines

Use these commands to allocate compute, inspect it, and control its lifecycle. See Lifecycle for state transitions and persistence behavior.

Command	Flags	What it does and when to use it
dedalus machines create	Optional: --vcpu, --memory-mib, --storage-gib, --autosleep.	Requests a Machine. Run without flags to get a default machine. Set flags to specify machine resources and autosleep behavior.
dedalus machines retrieve	Required: --machine-id.	Returns the Machine’s current resources, desired state, lifecycle status, and autosleep policy.
dedalus machines update	Required: --machine-id. Changes: --vcpu, --memory-mib, --storage-gib, --autosleep.	Requests one or more resource or autosleep changes. Use watch to wait for the Machine to reach its updated state.
dedalus machines list	Optional: --limit, --cursor, --max-items.	Lists Machines in the account. --limit sets the API page size, --cursor continues from a previous page, and --max-items caps the total number of Machines printed.
dedalus machines sleep	Required: --machine-id.	Requests a transition to sleeping, which stops compute while preserving the filesystem. Use watch when later work must wait for sleep to finish.
dedalus machines wake	Required: --machine-id.	Requests a transition from sleeping to running using the persisted filesystem. Use watch before sending work that requires the Machine to be ready.
dedalus machines watch	Required: --machine-id. Optional: --last-event-id, --max-items.	Streams lifecycle events until the Machine reaches its desired state. Use --last-event-id to resume an interrupted stream.
dedalus machines delete	Required: --machine-id.	Removes a Machine from normal use. Use it when the workspace is no longer needed.

Executions

An execution runs a non-interactive command inside a Machine and returns immediately. Use the returned execution_id to check status and read results. See Executions for the full asynchronous workflow.

Command	Flags	What it does and when to use it
dedalus machines executions create	Required: --machine-id, --command. Optional: --cwd, --env, --stdin, --timeout-ms.	Starts a command and returns an execution ID. Use it for agent actions, scripts, and background jobs.
dedalus machines executions retrieve	Required: --machine-id, --execution-id.	Returns current execution status. Poll it until the execution succeeds, fails, is cancelled, or expires.
dedalus machines executions list	Required: --machine-id. Optional pagination flags.	Lists executions for one Machine. Use it to inspect recent work or recover an execution ID.
dedalus machines executions events	Required: --machine-id, --execution-id. Optional pagination flags.	Lists standard output (stdout), standard error (stderr), and lifecycle events. Use it when output order or progress matters.
dedalus machines executions output	Required: --machine-id, --execution-id.	Returns captured stdout and stderr after an execution finishes.
dedalus machines executions delete	Required: --machine-id, --execution-id.	Cancels a running execution. It has no effect after the execution has already finished.

SSH sessions

Use dedalus ssh for a human shell. The nested machines ssh commands expose the underlying session resource for custom clients. See SSH for the authorization and host-verification contract.

Command	Flags and arguments	What it does and when to use it
dedalus ssh <machine_id>	Required argument: machine_id.	Generates a temporary SSH key pair, wakes the Machine if needed, verifies the host’s identity, and opens local OpenSSH.
dedalus machines ssh create	Required: --machine-id, --public-key.	Creates raw SSH authorization for a supplied public key. Use it when another tool owns the SSH client.
dedalus machines ssh retrieve	Required: --machine-id, --session-id.	Returns session status and connection material. Use it to wait for raw authorization to become ready.
dedalus machines ssh list	Required: --machine-id. Optional pagination flags.	Lists SSH sessions for one Machine.
dedalus machines ssh delete	Required: --machine-id, --session-id.	Ends an SSH session authorization.

Usage

Usage commands read billing data for the organization associated with the API key. Dates use YYYY-MM-DD in Coordinated Universal Time (UTC).

Command	Flags	What it does and when to use it
dedalus usage retrieve	Optional: --period-start.	Returns the organization’s usage summary from the requested date or the start of the current month.
dedalus usage machine-compute	Optional: --machine-id, --period-start, --period-end, --granularity.	Breaks compute usage down by Machine and hour or day. Use it to see which Machines account for usage and how usage changes over time.
dedalus usage machine-storage	Optional: --machine-id, --period-start, --period-end.	Breaks storage usage down by Machine and date.

Local CLI operations

Command	Flags and arguments	What it does and when to use it
dedalus update	Optional: --check.	Checks for the latest release. Without --check, it updates supported installations or prints the correct manual command.
dedalus --version	None.	Prints the installed CLI version. Use it when checking compatibility or reporting a problem.
dedalus --help	None.	Lists command families and global flags for the installed version.
dedalus <command> --help	None beyond the command path.	Lists the flags and nested actions available at that point in the command tree.
dedalus @completion <shell>	Required argument: bash, zsh, fish, or pwsh.	Writes a shell-completion script to standard output. Save or source it to enable command and flag completion.

Control input and output

The default output format is JSON. Use --format for human-readable YAML or the interactive explorer:

dedalus machines list --format yaml

Example output:

machine_id: dm-0199a1b2-c3d4-7000-8000-000000000001
vcpu: 2
memory_mib: 4096
storage_gib: 20
autosleep_seconds: 900
desired_state: running
phase: accepted
created_at: "2026-09-02T20:30:00Z"

Use explore to open the same data in an interactive table. The CLI adjusts column widths to fit the terminal.

dedalus machines list --format explore

Example output:

  machines list
╭──────────────────────────────────────────────────────────────────────────────╮
│ machine_id  vcpu  memory_…  storage…  autosle…  desired…  phase     created… │
│──────────────────────────────────────────────────────────────────────────────│
│ dm-0199a1…  2     4096      20        900       running   accepted  2026-09… │
╰──────────────────────────────────────────────────────────────────────────────╯
q/enter quit • ↑/k up • ↓/j down • ←/h go back • →/l expand • p print and exit

GJSON is the field-selection syntax for CLI JSON output. Use GJSON path syntax to transform each list item. This example prints one Machine ID per line without JSON quotes:

dedalus machines list --transform machine_id --raw-output

Commands with a request body also accept JSON or YAML from standard input:

dedalus machines create <<'YAML'
vcpu: 2
memory_mib: 4096
storage_gib: 20
autosleep: 15m
YAML

Run dedalus <command> --help to inspect pagination flags and accepted input fields. Run dedalus --help to see the global output formats for your version.

Shell completions

Homebrew installs completions automatically. Manual installations can generate a script for Bash, zsh, Fish, or PowerShell. The command writes the script to standard output; source it for the current session or save it where your shell loads completions.

dedalus @completion bash > dedalus.bash
dedalus @completion zsh > _dedalus
dedalus @completion fish > dedalus.fish
dedalus @completion pwsh > dedalus.ps1

Command reference

The CLI generates its reference from the same command tree it executes. Add --help at any level to see the exact flags and nested commands in the installed release:

dedalus --help
dedalus machines --help
dedalus machines executions create --help

See the CLI repository for release notes and source code.