Install and sign in

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

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 variable	Effect
`INSTALL_DIR`	Install somewhere else — e.g. `/usr/local/bin` on a CI image, so the binary is already on `PATH`.
`OAK_NO_LOGIN=1`	Skip the "Log in now?" prompt at the end. (It's skipped automatically when there's no terminal.)

On macOS the installer also fetches the Oak Mount app that lazy mounts need; if it can't, the first oak mount installs it instead. See Setting up mounts.

Linux ARM64: binaries are published on the GitHub releases page, but the installer doesn't select them yet. Download oak for linux-arm64 from there and put it on your PATH.

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 ~/.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.

Self-hosted or staging servers#

Every command that talks to a server takes -r, --remote <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             # latest stable release
oak upgrade --canary    # track the rolling pre-release channel

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 zsh  > ~/.zfunc/_oak                                     # zsh
oak completions bash > ~/.local/share/bash-completion/completions/oak    # bash
oak completions fish > ~/.config/fish/completions/oak.fish               # fish

elvish and powershell are supported 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

Uninstall#

Delete the binary (~/.local/bin/oak) and, if you want to drop your login and local mount state too, ~/.oak/. On macOS, also delete Oak Mount from /Applications. 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].