> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dedaluslabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install, update, and use the Dedalus CLI for Cloud Services.

The Dedalus CLI manages Dedalus Cloud Services (DCS) from a terminal or automated
workflow. API commands group actions under resources such as `machines` and `usage`.

This guide covers stable workflows and command families. For the exact commands
and flags supported by your installed version, use the generated `--help` output.

## Install

<CodeGroup>
  ```bash Homebrew theme={"theme":{"light":"github-light","dark":"github-dark"}}
  brew install dedalus-labs/tap/dedalus
  ```

  ```bash Go theme={"theme":{"light":"github-light","dark":"github-dark"}}
  go install github.com/dedalus-labs/dedalus-cli/cmd/dedalus@latest
  ```

  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -fsSL https://www.dedaluslabs.ai/install/dedalus | bash
  ```

  ```powershell PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
  irm https://raw.githubusercontent.com/dedalus-labs/dedalus-cli/main/scripts/install.ps1 | iex
  ```
</CodeGroup>

<Note>
  Homebrew installs the version currently published in the tap. Compare
  `dedalus --version` with the [latest CLI release](https://github.com/dedalus-labs/dedalus-cli/releases/latest);
  if the tap trails the release, use Go, curl, or PowerShell.
</Note>

Verify the installation and inspect the available commands:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dedalus --version
dedalus --help
```

## Authenticate

Create an API key in the [Dedalus Dashboard](https://dedaluslabs.ai/dashboard/api-keys),
then export it in your shell:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

Verify that the CLI can access your account:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dedalus machines list
```

## Update

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`; other
unrecognized installs receive manual instructions.

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.

## Command structure

API commands follow the resource hierarchy:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
dedalus <resource> <action> [flags]
dedalus machines <subresource> <action> [flags]
```

| Command family                   | Use it to                                                             |
| -------------------------------- | --------------------------------------------------------------------- |
| `dedalus machines`               | Create, inspect, update, delete, sleep, wake, and watch Machines.     |
| `dedalus machines <subresource>` | Manage artifacts, executions, previews, SSH sessions, and terminals.  |
| `dedalus usage`                  | Inspect organization totals and per-Machine compute or storage usage. |
| `dedalus ssh`                    | Open an SSH session to a running Machine.                             |
| `dedalus update`                 | Check for or install a newer CLI release.                             |

### Manage a Machine

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dedalus machines create \
  --vcpu 1 \
  --memory-mib 2048 \
  --storage-gib 10 \
  --autosleep 15m
dedalus machines list
dedalus machines retrieve --machine-id dm-abc123
dedalus machines update --machine-id dm-abc123 --autosleep never
dedalus machines watch --machine-id dm-abc123
```

See [Machine lifecycle](/dcs/dm/lifecycle) for the state model and operations.

### Work with Machine resources

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dedalus machines executions create \
  --machine-id dm-abc123 \
  --command '["echo", "hello"]'
dedalus machines artifacts list --machine-id dm-abc123
dedalus machines terminals list --machine-id dm-abc123
dedalus machines previews list --machine-id dm-abc123
dedalus ssh dm-abc123
```

For workflow details, see [Executions](/dcs/dm/executions), [Terminals](/dcs/dm/terminals),
[Ports](/dcs/dm/ports), and [SSH](/dcs/dm/ssh).

### Inspect organization usage

Usage commands use the organization associated with your API key:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dedalus usage retrieve
dedalus usage machine-compute --granularity day
dedalus usage machine-storage --machine-id dm-abc123
```

## Control input and output

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dedalus machines list --format yaml
dedalus machines list --format explore
```

GJSON is the field-selection syntax for CLI JSON output. Use
[GJSON path syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md) to
transform each list item. This example prints one Machine ID per line without
JSON quotes:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dedalus machines list --transform machine_id --raw-output
```

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dedalus --help
dedalus machines --help
dedalus machines executions create --help
```

See the [CLI repository](https://github.com/dedalus-labs/dedalus-cli) for
release notes and source code.