How do I install the Oxen.ai CLI (Homebrew/Linux/Windows) and log in with an API key?

Most teams hit the same wall the moment they want to treat datasets and model weights like real versioned assets: you need a CLI that’s easy to install on every dev machine, works on CI, and authenticates cleanly with your Oxen.ai account. The Oxen CLI is that glue layer. Install it once, log in with an API key, and you can version datasets, sync large files, kick off fine-tunes, and wire Oxen into your pipelines.

Quick Answer: Install the Oxen.ai CLI using Homebrew on macOS, the prebuilt binary or package manager on Linux, or the installer/executable on Windows. Then create an API key from your Oxen.ai account, run oxen login --api-key <YOUR_KEY>, and you’re authenticated to push/pull datasets, manage repositories, and integrate Oxen into your workflows and CI.

Why This Matters

If you want to go from “prototype notebook” to “repeatable dataset → fine-tune → deploy loop,” you need a single interface that works across laptops, servers, and CI. The Oxen.ai CLI gives you that: Git-style commands for large datasets and model weights, wired directly into your Oxen repositories and model endpoints.

When every contributor uses the same CLI and authenticates with API keys, you can:

• script data uploads instead of drag-dropping to random buckets,
• tie model versions back to specific dataset snapshots, and
• integrate Oxen into real release pipelines instead of ad-hoc shell scripts.

Key Benefits:

• Consistent workflow across environments: Use the same oxen commands on macOS, Linux, and Windows (including CI runners).
• Secure, scriptable auth with API keys: Avoid copying cookies or magic links; use scoped API keys for automation and team workflows.
• Fast path from data to deployment: Once the CLI is installed and logged in, you can version datasets, trigger fine-tunes, and hook Oxen into your build and release pipeline.

Core Concepts & Key Points

Concept	Definition	Why it's important
Oxen CLI	A command-line interface (oxen) to create repos, version datasets/model weights, and interact with Oxen.ai.	It’s the backbone of your “Build Datasets. Train Models. Own Your AI.” workflow, from local dev to CI and production.
API Key Login	Authenticating the CLI using a secret token generated from your Oxen.ai account.	Makes it safe and easy to script CLI calls, onboard teammates, and run Oxen in headless environments.
Cross-Platform Install	Installing the CLI via Homebrew (macOS), Linux binaries/package managers, or Windows installers.	Ensures every contributor—regardless of OS—can use the same commands and access the same datasets and models.

How It Works (Step-by-Step)

At a high level, the flow is:

1. Install the Oxen CLI for your OS (Homebrew on macOS, package/binary on Linux, installer or choco on Windows).
2. Verify the install and check the version.
3. Generate an API key from your Oxen.ai account and log in from the CLI.
4. Optionally, set environment variables or config files for CI and shared machines.

1. Install the Oxen CLI on macOS (Homebrew)

If you’re on macOS, Homebrew is the cleanest way to keep oxen updated.

Prerequisite: Homebrew installed (brew -v should work).

# Add the Oxen tap (if required)
brew tap oxen-ai/oxen

# Install the CLI
brew install oxen

# Or, if the formula lives directly in homebrew-core
# brew install oxen-ai

Verify the install:

oxen --version

If your shell can’t find oxen, make sure your Homebrew bin directory is on your PATH (usually /opt/homebrew/bin on Apple Silicon or /usr/local/bin on Intel Macs):

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. Install the Oxen CLI on Linux

You’ve got two primary installation patterns on Linux: package manager or direct binary download. The exact command may differ depending on how Oxen distributes builds in your environment; the patterns below show the typical approaches.

Option A: Install via package manager (Debian/Ubuntu-style)

If Oxen provides an APT repository:

# 1. Add the Oxen GPG key and repo (example commands)
curl -fsSL https://download.oxen.ai/linux/oxen.gpg | sudo gpg --dearmor -o /usr/share/keyrings/oxen.gpg

echo "deb [signed-by=/usr/share/keyrings/oxen.gpg] https://download.oxen.ai/linux stable main" \
  | sudo tee /etc/apt/sources.list.d/oxen.list

# 2. Update and install
sudo apt update
sudo apt install oxen

Check it worked:

oxen --version

Option B: Download a standalone binary

If you don’t have root or you’re on a distro without a dedicated package:

# Replace VERSION and ARCH with the latest release and arch, e.g. linux-x86_64
OXEN_VERSION="vX.Y.Z"
OXEN_ARCH="linux-x86_64"

curl -L "https://download.oxen.ai/cli/${OXEN_VERSION}/oxen-${OXEN_ARCH}" -o oxen
chmod +x oxen
sudo mv oxen /usr/local/bin/oxen

Then verify:

oxen --version

If /usr/local/bin isn’t on your PATH, add it to your shell config:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

3. Install the Oxen CLI on Windows

On Windows, you can either use a package manager like Chocolatey or install via a downloadable installer/executable.

Option A: Install via Chocolatey

Prerequisite: Chocolatey installed and running PowerShell as Administrator.

choco install oxen -y

After install, check:

oxen --version

Option B: Install via installer or standalone EXE

If Oxen provides an .msi or .exe:

1. Download the installer from your Oxen.ai account or the official download page.

2. Run the installer and follow the prompts (ensure “Add to PATH” is selected if offered).

3. Open a new PowerShell or Command Prompt and run:

   oxen --version
   

If oxen isn’t recognized, add its install directory (for example, C:\Program Files\Oxen\) to your system PATH via System Properties → Environment Variables.

---

Log In to the Oxen CLI with an API Key

Once oxen is available in your terminal, you’ll log in using an API key. This keeps your workflow scriptable and avoids brittle browser-based auth for headless environments.

1. Generate an API key in Oxen.ai

1. Go to https://www.oxen.ai and log in.
2. From your account/profile settings, open the API Keys or Developer section.
3. Click Create New API Key.
4. Give it a descriptive name, like laptop-maya, ci-github-actions, or data-ingest-prod.
5. Copy the key immediately and store it somewhere secure (password manager, secrets manager). You won’t be able to see the full value again.

Treat this key like a password. Anyone with it can act as your account from the CLI.

2. Log in via oxen login --api-key

From your terminal:

oxen login --api-key YOUR_OXEN_API_KEY

The CLI will:

• store the token in a local config (typically under your home directory),
• confirm that you’re authenticated, and
• use this token for subsequent commands (creating repos, pushing data, etc.).

You can verify that you’re logged in:

oxen whoami

If configured correctly, you should see your Oxen username or account info.

3. Use environment variables for CI and shared machines

For CI and other non-interactive environments, don’t hardcode keys in scripts. Use environment variables and a headless login pattern.

Set the key in your CI provider as a secret (e.g., OXEN_API_KEY), then in your job setup:

# Bash-style
oxen login --api-key "$OXEN_API_KEY"

Or, if the CLI supports reading directly from env without explicit arguments, you might use:

export OXEN_API_KEY=your_key
oxen login

(Adjust to your team’s preferred secret management; the core idea is the same: never commit keys; always inject them via env.)

---

Common Mistakes to Avoid

• Exposing your API key in source control:
  Don’t paste oxen login --api-key XXXXXX into versioned scripts. Use environment variables or CI secrets instead so keys never hit Git history.

• Mixing personal and CI credentials on the same machine:
  On shared build machines or long-lived dev servers, avoid manually running oxen login with your personal key if CI jobs also log in. Use separate service keys per environment and reset or clear credentials (oxen logout) when repurposing machines.

---

Real-World Example

Imagine you’ve got a product team collecting real user prompts to fine-tune a support model. You want to version this dataset, review it with stakeholders, and wire it into a nightly pipeline that retrains and deploys a better model behind a serverless endpoint.

A minimal setup might look like:

# 1. Install and log in (once per machine)
brew install oxen
oxen login --api-key "$OXEN_API_KEY"

# 2. Initialize a dataset repo and push data
oxen init support-prompts
cd support-prompts

# Add your data (JSONL, CSV, images, audio, etc.)
cp ../exports/*.jsonl .
oxen add .
oxen commit -m "Initial batch of support prompts (2026-04-12)"
oxen push origin main

Now your dataset—and its exact version history—is in Oxen. From there, you can:

• use Oxen’s zero-code fine-tuning to train a custom model in a few clicks,
• deploy that model to a serverless endpoint,
• and tie your nightly pipeline to “new data in this repo” instead of brittle S3 paths.

Pro Tip: Create one API key per context—dev-laptop, staging-ci, prod-ci—and rotate them periodically. If a key ever leaks, you can revoke just that key without disrupting your entire team.

Summary

Getting the Oxen.ai CLI installed and logged in is the unlock for a disciplined, repeatable data-to-model workflow. Install oxen via Homebrew (macOS), package/binary (Linux), or Chocolatey/installer (Windows), then authenticate once with an API key. From there, you can version every dataset and model weight, collaborate across your team, and drive fine-tuning and deployment from real, auditable data history—without fighting S3 sync scripts or wondering which data trained which model.

Next Step

Get Started