Skip to content
On this page


OrbStack can be used entirely from the command line, making the GUI app optional. You can use and manage Linux machines, run commands, and transfer files without leaving the terminal.

To get started:

orb help


orb is a short all-in-one command that serves several purposes.

Start a shell

Run orb with no arguments to start a shell in the default Linux machine:


You can also specify a machine and user:

orb -m my-machine -u my-user

Run orbctl shell --help for more options.

Run a command

Prefix a command with orb to run it in Linux:

orb uname -a

To specify a machine and user:

orb -m my-machine -u my-user uname -a

Run orbctl run --help for more options.

Manage machines

Run orb with a subcommand to manage machines. For example, to create a new Ubuntu machine:

orb create ubuntu my-machine

Many other subcommands are available:

config      Configure the Linux virtual machine
  create      Create a new Linux machine
  default     Get or set the default machine
  delete      Delete a Linux machine
  docker      Show commands for using Docker
  info        Get information about a Linux machine
  list        List all Linux machines
  pull        Copy files from Linux
  push        Copy files to Linux
  reset       Delete all Linux and Docker data
  restart     Restart a Linux machine
  run         Run command on Linux
  shutdown    Stop the lightweight Linux virtual machine
  ssh         Show SSH details
  start       Start Linux machines
  stop        Stop a Linux machine
  update      Update OrbStack

Run orb <command> --help for more information about each command.


You can also use orbctl to manage machines explicitly. Unlike the shorter orb command, you must use orbctl shell or orbctl run to start a shell or run a command.

File transfer

You can use orb pull and orb push to copy files to and from Linux machines. For example, to copy a file from Linux to Mac:

orb pull ~/foo.txt

To copy a file from Mac to Linux:

orb push ~/bar.txt

You can also specify a machine and destination:

orb push -m my-machine ~/bar.txt /home/my-user/code/


Prefix a command with mac to run it on macOS:

mac uname -a

There are also several subcommands for integration:

link        Link a command to macOS
  notify      Send a macOS notification
  pull        Copy files from macOS
  push        Copy files to macOS
  run         Run command on macOS
  unlink      Unlink a macOS command

Linking commands

You can use mac link to link a macOS command to Linux. Linked commands do not need to be prefixed with mac to run and can be used as if they were native to Linux.

For example, to link the pbcopy command:

mac link pbcopy

open, osascript, and code are linked by default.


Similar to orbctl, you can use macctl to run macOS integration subcommands explicitly.