OrbStack Docs

Appearance

Commands ​

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:

bash
orb help
orb help

orb ​

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:

bash
orb
orb

You can also specify a machine and user:

bash
orb -m my-machine -u my-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:

bash
orb uname -a
orb uname -a

To specify a machine and user:

bash
orb -m my-machine -u my-user uname -a
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:

bash
orb create ubuntu my-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
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.

orbctl ​

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:

bash
orb pull ~/foo.txt
orb pull ~/foo.txt

To copy a file from Mac to Linux:

bash
orb push ~/bar.txt
orb push ~/bar.txt

You can also specify a machine and destination:

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

mac ​

Prefix a command with mac to run it on macOS:

bash
mac uname -a
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
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:

bash
mac link pbcopy
mac link pbcopy

open, osascript, and code are linked by default.

macctl ​

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

© 2024 Orbital Labs, LLC