---
id: bastos/skills/orbstack-cli
version: "02b47dcd"
license: MIT
install: manual
updated: 2026-07-22
---

# orbstack-cli — OrbStack CLI is the command reference and recipe book for driving OrbStack—a Docker and Linux VM runtime for macOS—from the terminal. It covers the orb and orbctl commands for machine lifecycle management, file transfer, Docker operations, container domains, networking, and CI automation.

Publisher: bastos · Stars: 4 · Updated: 2026-07-22

Install (manual): `git clone https://github.com/bastos/skills`

## SKILL.md

# OrbStack CLI

OrbStack is a fast Docker + Linux VM runtime for macOS (a Docker Desktop
replacement). You drive it from the terminal with four commands. This skill is
the **command index and recipe book**; read the matching `references/` file when
you need full flags or detail.

## Which command do I use?

| Command | Use it for |
|---------|-----------|
| `orb` (no args) | Open a shell in the **default** Linux machine |
| `orb <cmd> [args]` | Run `<cmd>` **inside** the default Linux machine (e.g. `orb uname -a`) |
| `orb <subcommand>` / `orbctl <subcommand>` | **Manage** OrbStack and its machines (create, start, config, logs...) |
| `docker` / `docker compose` / `kubectl` | Build/run containers and Kubernetes - run these straight from macOS, no VM needed |
| `mac <cmd>` | Run a **macOS** command from *inside* a Linux machine (e.g. `mac open`, `mac notify`) |

`orb` and `orbctl` are the same binary: `orb foo` runs `foo` in Linux, but
`orb create`/`orb start`/etc. (any known subcommand) manage OrbStack. When a name
could collide, prefer `orbctl <subcommand>` to be explicit.

## Cheat sheet (most common)

```bash
# Machines
orb create ubuntu                       # newest Ubuntu, VM named "ubuntu"
orb create ubuntu:24.04 dev             # specific version + name
orb list                                # list machines + status
orb                                     # shell into default machine
orb -m dev -u root apt update           # run a command in "dev" as root
orb push ~/file.txt code/               # copy Mac -> Linux (~/code/)
orb pull code/out.log .                 # copy Linux -> Mac
orb stop dev / orb start dev / orb delete dev

# Docker (just use docker; OrbStack is the "orbstack" context)
docker run -p 80:80 nginx               # then visit http://localhost
docker run -l dev.orbstack.domains=app.local nginx   # custom domain

# Kubernetes
orb start k8s && kubectl get pods -A

# Service control / health
orb status                              # Running=0, Stopped=1, Starting=2
orb doctor --fix                        # verify + repair Docker integration
orb restart docker                      # restart just the Docker engine

# Config (see `orb config show` for all keys)
orb config set memory_mib 8192
orb config set cpu 4
```

## Key facts you can rely on

- **Auto port-forwarding:** a server listening inside a container or VM is
  reachable on the same port on macOS `localhost` - no `-p` needed for VMs, and
  containers are *also* reachable by domain without any mapping.
- **Domains:** every container is at `<name>.orb.local`; compose services at
  `<svc>.<project>.orb.local`; VMs at `<machine>.orb.local`. All get zero-config
  HTTPS. Visit `https://orb.local` for an index of running containers. → `references/domains.md`
- **Docker context** is named `orbstack` and is selected automatically. If
  `docker` says "cannot connect to the daemon": `docker context use orbstack`
  or `orb doctor --fix`. → `references/docker.md`
- **File paths:** Linux files from macOS at `~/OrbStack/<machine>/`; macOS files
  from Linux at `/mnt/mac/...`; Docker volumes at `~/OrbStack/docker/volumes/`.
- **Exit codes** make `orb` scriptable: `orb status` (0/1/2), `orb update -c`
  (0 = current, 3 = outdated). → `references/headless.md`

## Full command index

Every `orbctl`/`orb` subcommand. Read the linked reference for flags + examples.

| Subcommand | What it does | Reference |
|-----------|--------------|-----------|
| `create` | Create a Linux machine (distro\[:version] \[name]) | machines.md |
| `list` / `info` | List machines / show one machine's details (`-f json`) | machines.md |
| `default` | Get or set the default machine | machines.md |
| `start` / `stop` / `restart` | Start/stop/restart machine(s); bare `orb stop` stops **all** of OrbStack | machines.md |
| `delete` | Permanently delete machine(s) (`-a` all, `-f` force) | machines.md |
| `clone` / `rename` | Copy / rename a machine | machines.md |
| `export` / `import` | Save a machine to / restore from a `.tar.zst` | machines.md |
| `run` (alias `exec`/`shell`) | Run a command in a machine (`-m`, `-u`, `-w`, `ORBENV`) | machines.md |
| `push` / `pull` | Copy files Mac↔Linux | machines.md |
| `logs` | Unified machine logs (`-a` for all/debug) | machines.md, troubleshooting.md |
| `ssh` | Print SSH connection details | ssh.md |
| `usb` / `serial` | USB passthrough (attach/detach/list/info) / serial devices | machines.md |
| `docker` | Docker **extension** cmds: `volume` (clone/export/import), `migrate` | docker.md |
| `debug` (Pro) | Open a debug shell with tools in any container | docker.md |
| `k8s` | Show Kubernetes usage (`orb start k8s`) | kubernetes.md |
| `config` | get/set/add/remove/show/reset settings; `config docker` edits engine JSON | config.md |
| `status` | Is OrbStack running? (exit 0/1/2) | headless.md |
| `update` | Update OrbStack (`-c` check only, exit 3 if outdated) | headless.md |
| `top` | Live activity monitor (CPU/mem/disk/net) | troubleshooting.md |
| `doctor` | Verify Docker integration (`--fix` to repair) | troubleshooting.md |
| `report` / `reset` | Diagnostic bug report / factory reset (destroys data) | troubleshooting.md |
| `login` / `logout` | Manage OrbStack account + Pro license | config.md |
| `version` | Show version | - |
| `completion` | Generate shell completions (bash/zsh/fish/powershell) | config.md |

## Reference files

Read on demand:

- **`references/machines.md`** - full machine lifecycle, `run`/exec, file
  transfer, per-VM CPU/memory/disk limits, isolation, cloud-init, USB/serial,
  and running macOS commands from Linux (`mac`, `ORBENV`).
- **`references/docker.md`** - using `docker` under OrbStack: context, platform/
  Rosetta, volume extension commands, migrating from Docker Desktop, debug
  shell, SSH-agent forwarding, checkpoints, credential store, engine config.
- **`references/domains.md`** - `.orb.local` naming, custom domains label,
  HTTP-port override, wildcards, HTTPS, compose + k8s domains.
- **`references/networking.md`** - port-forwarding, reaching the Mac host
  (`host.docker.internal`), direct container IPs, IP ranges, proxies, IPv6, LAN
  exposure, VPN, self-signed registry certs.
- **`references/ssh.md`** - `ssh orb` patterns, port 32222, key path, IDE setup
  (VS Code / JetBrains / Fleet), Ansible, authorized_keys.
- **`references/kubernetes.md`** - start/stop the cluster, kubectl context,
  kubeconfig, service domains, exposing services.
- **`references/config.md`** - `orb config` subcommands and a full reference of
  every config key with its meaning.
- **`references/headless.md`** - CLI/CI automation: install, service start/stop,
  status + exit codes, non-interactive provisioning, disabling admin prompts and
  context switching, JSON output.
- **`references/troubleshooting.md`** - `doctor`/`report`/`reset`, restarting the
  engine, fixing the Docker context, Rosetta arch errors, cloud-init debugging,
  and the published-port "wedge" / route-loss gotchas.


[View on SkillFed](https://skillfed.io/bastos/skills/orbstack-cli) · [View on GitHub](https://github.com/bastos/skills)