Install and sign in

Install the oak CLI on macOS, Linux, or Windows, sign in, and keep it up to date.

Markdown

All pages

Install the CLI#

On macOS (Apple Silicon or Intel) and Linux x86_64:

curl -fsSL https://oak.space/install | sh

On Windows x86_64, from PowerShell:

irm https://oak.space/install.ps1 | iex

The installer picks the native binary for your machine, verifies its minisign signature, and puts it at ~/.local/bin/oak (%USERPROFILE%\.local\bin\oak.exe on Windows). If that directory isn't on your PATH, the installer prints the line to add.

Installer variableEffect
INSTALL_DIRInstall somewhere else — e.g. /usr/local/bin on a CI image, so the binary is already on PATH.
OAK_NO_LOGIN=1Skip the "Log in now?" prompt at the end. (It's skipped automatically when there's no terminal.)

Linux ARM64: a binary is published, but the installer doesn't select it yet. Download it from https://oak.space/api/releases/latest/linux-arm64, rename it to oak, make it executable, and put it on your PATH.

Sign in#

oak login
oak whoami        # prints the username you're signed in as

oak login opens your browser at oak.space, where you sign in however you normally do (password or GitHub), and hands a token back to the CLI over a one-shot local callback. On a machine with no browser — an SSH session, a container — it prints a URL instead: open it on any other device, approve, and paste the one-time code it shows back into the terminal.

The token is saved in ~/.config/oak/credentials and lasts 90 days. Run oak login again to refresh it, or oak logout to remove it.

To check which credential the CLI is actually using — handy when a push 404s on a repo you know exists — run:

oak auth status

It reports where the credential came from (never the secret itself), which server, and the identity the server resolves it to.

Non-interactive machines and CI#

oak login needs a human once. For scripts, CI jobs, and long-running agents, use an API key instead and export it:

export OAK_API_KEY=oak_...

OAK_API_KEY beats every stored credential. Create keys — including narrowly scoped, read-only, or single-repo keys — as described in API keys and tokens.

Other servers#

Every command that talks to a server takes --server <URL> (default https://oak.space). You can also set OAK_REMOTE for a whole shell. Once a checkout is linked to a server, it remembers which one.

Keep it up to date#

oak upgrade

There is one release line during the beta, released once a day (2 PM Pacific) on days when something landed. Upgrades are signature-checked like the installer. The CLI checks for a new version at most once a day and prints a one-line notice; set OAK_NO_UPDATE_CHECK=1 to turn that off.

Shell completion#

oak completions --install

This writes the completion script for your shell (from $SHELL, or name it: oak completions --install zsh) to where that shell loads completions from: ~/.zfunc/_oak for zsh, ~/.local/share/bash-completion/completions/oak for bash, ~/.config/fish/completions/oak.fish for fish. If your startup file is missing a line the shell needs to load it, such as zsh's fpath and compinit, Oak prints the line for you to add. It doesn't edit startup files.

To print the script instead, give the shell name: oak completions zsh. elvish and powershell can be printed this way too.

Teach your agent#

If you use a coding agent, install the bundled skill in each repo you work in:

oak skill install            # into ./.claude/skills/ — commit it
oak skill install --global   # or into ~/.claude/skills/ for every project

More in Working with agents.

Uninstall#

Delete the binary (~/.local/bin/oak) and, if you want to drop your login and other local state too, ~/.config/oak/. Repositories you've cloned are ordinary directories; each one's Oak metadata lives in its own .oak/ folder.

Next: Quickstart.

Something here wrong or missing? Run oak feedback -m "…" or email [email protected].