Skip to Content
homemade
Dashboard

CLI

Install the homemade CLI, sign in, and work with your VMs from a terminal, a script or a coding agent.

The homemade CLI is one small program for macOS and Linux, with nothing else to install.

Install

curl -fsSL https://homemade.dev/install.sh | bash
homemade --version

Or with Homebrew on macOS and Linux:

brew install usehomemade/tap/homemade

The installer puts homemade in ~/.local/bin (set HOMEMADE_INSTALL_DIR to choose another folder) and adds that folder to your shell's PATH. Open a new terminal afterwards.

homemade upgrade installs the newest release where the CLI already is (or runs brew upgrade homemade for a Homebrew install).

Sign in

homemade login

This opens your browser to confirm the sign-in. homemade whoami shows who you are signed in as and your teams.

Choose the team and project that commands use by default:

homemade use acme/storefront

Any command also takes --org and --project to override it. homemade logout signs out on this machine.

Use it in CI

Create an API key once and store it in your CI provider's secrets. The key is shown only once.

homemade api-key create --name ci

Then pass it as an environment variable. It wins over a signed-in session:

HOMEMADE_API_KEY="$CI_HOMEMADE_API_KEY" homemade project list

Output is made for scripts: results go to stdout, errors to stderr, and --json prints the API's answer unchanged. Exit codes: 0 done, 1 the API or network failed, 2 wrong usage or not confirmed, 3 not signed in, 4 not found, 124 timed out.

VMs

Commands take a VM's name (like misty-fern-142) or its id, and a project's slug or id.

homemade vm create --branch fix-auth --wait   # returns once the VM runs
homemade vm list
homemade vm get misty-fern-142
homemade vm sleep misty-fern-142
homemade vm wake misty-fern-142
homemade vm delete misty-fern-142

--wait stops after 10 minutes with exit code 124; change that with --wait-timeout <seconds>.

Run one command in a running VM. The exit code is the command's own:

homemade vm exec misty-fern-142 -- pnpm test
homemade vm exec misty-fern-142 -- 'cd app && npm run lint'

Terminals

Terminals belong to the VM, not to your connection: they keep running when you leave.

homemade shell create my-vm --name dev --cmd "pnpm dev"
homemade shell attach my-vm --session dev
homemade shell send   my-vm --session dev "git status"
homemade shell read   my-vm --session dev
homemade shell list   my-vm
homemade shell delete my-vm <session-id>
  • --session takes a session id, the start of one, or a terminal's name. Without it, the command picks the newest session.
  • In an attached terminal, type ~. at the start of a line to detach.
  • shell send with - as the text reads it from stdin.

SSH and editors

homemade open my-vm                   # opens it in VS Code
homemade open my-vm --editor cursor   # or in Cursor
homemade open my-vm --print           # prints the ssh and editor commands only
homemade open my-vm --web             # opens the VM page in the dashboard

open adds a section to ~/.ssh/config the first time, so that ssh, VS Code and Cursor can reach your VMs. Running it again is safe; it only rewrites its own section.

For a quick session, or one command:

homemade ssh my-vm
homemade ssh my-vm -- cat package.json

Register your SSH public key so every VM in your teams accepts it:

homemade ssh-key add               # reads ~/.ssh/id_ed25519.pub and friends
homemade ssh-key list
homemade ssh-key delete <id>

Check your config

homemade config validate          # looks in .homemade/ under this folder
homemade config validate ../shop

It checks .homemade/config.json or .jsonc with the same rules a build uses. A .ts or .js config is checked at the first build instead.

Coding agents (MCP)

homemade mcp is an MCP server for Claude Code, Cursor and other agents. It has one tool for every API operation, and uses your login or HOMEMADE_API_KEY.

claude mcp add homemade -- homemade mcp

In other clients, add a stdio server with the command homemade and the argument mcp.

Help and completions

Every command has its own help: homemade --help, homemade vm --help, homemade api-key create --help.

Shell completions for bash, zsh and fish:

source <(homemade completion bash)   # add to ~/.bashrc
source <(homemade completion zsh)    # add to ~/.zshrc
homemade completion fish | source    # add to ~/.config/fish/config.fish

Confirmations

Commands that can't be undone ask first. homemade project delete asks you to type the project's slug, because it deletes every VM in the project too; the others ask yes or no. Pass --yes (or -y) to skip the question. Without a terminal to ask in, they stop unless you pass --yes.

Updates

When your CLI is too old for the API, commands stop with a message to upgrade. Run homemade upgrade, then check with homemade --version.

The CLI collects no telemetry, analytics or crash reports.

On this page