---
title: Quickstart
description: Get axm installed, authenticated, and ready to use
---

# Quickstart

Get axm installed, authenticated, and ready to use. Pick the installation method that fits your environment, then follow the steps through verification.

## Choose Your Installation Method

| Method                            | Platforms             | Node.js Required | Best For                                            |
| --------------------------------- | --------------------- | ---------------- | --------------------------------------------------- |
| [Agent](#agent)                   | Any                   | Varies           | AI coding agents installing axm autonomously        |
| [Native Install](#native-install) | macOS, Linux, Windows | No               | Most users — standalone binary, nothing else needed |
| [Homebrew](#homebrew)             | macOS, Linux          | No               | Homebrew users who prefer `brew upgrade`            |
| [npx](#npx)                       | Any                   | Yes              | Trying axm without a global install                 |

---

## Agent

The recommended method for AI coding agents to install AXM autonomously.

Point your agent to the machine-readable install document:

```
https://axm.sh/install.md
```

This document contains step-by-step instructions in a TODO-checklist format that agents can parse and execute. It covers installation, authentication, and verification.

---

## Native Install

Downloads a standalone binary. No Node.js dependency.

### macOS and Linux (bash)

```bash
curl -fsSL https://axm.sh/install.sh | sh
```

### Windows (PowerShell)

```powershell
irm https://axm.sh/install.ps1 | iex
```

### Windows (CMD)

Download and run the install script directly:

```cmd
curl -fsSL -o install.cmd https://axm.sh/install.cmd && install.cmd
```

### Verify

```bash
axm --version
```

You should see output like `X.Y.Z`.

### Authenticate

```bash
axm login
```

This opens a browser for OAuth authorization. Grant access when prompted, then verify:

```bash
axm whoami
```

---

## Homebrew

Available on macOS and Linux. No Node.js dependency.

### Install

```bash
brew install axm-sh/tap/axm
```

### Verify

```bash
axm --version
```

### Authenticate

```bash
axm login
```

This opens a browser for OAuth authorization. Grant access when prompted, then verify:

```bash
axm whoami
```

---

## npx

Zero-install option for Node.js users. Good for trying axm without committing to a global install. Requires Node.js.

### Run

```bash
npx axm.sh
```

You can pass any axm command directly:

```bash
npx axm.sh --version
npx axm.sh login
npx axm.sh whoami
```

---

## Authentication

After installing axm through any method, you need to authenticate.

### Interactive (recommended for local development)

```bash
axm login
```

Opens a browser for AgentXM.ai authorization. Grant access when prompted.
On desktop systems this uses a local loopback callback with PKCE. Over SSH
without a display, in CI or Codespaces, on Linux with none of `DISPLAY`,
`WAYLAND_DISPLAY`, or `BROWSER` set (WSL excepted), or in `--device-code` mode,
AXM displays a five-minute device code and a complete authorization link, along
with the clean verification page for entering the code by hand. Press `c` while
it waits to copy the link; over SSH the copy reaches your local clipboard
through the terminal. Re-running the command reuses the same unexpired
request; pass `--restart` only to replace it intentionally.

Verify authentication:

```bash
axm whoami
# Expected: displays your handle, Registry, credential type, scopes, restrictions, and expiry
```

### Non-interactive (CI, scripts, agents)

Store a pre-provisioned token in a restrictive, readable file and provide its
path to AXM:

```bash
export AXM_TOKEN_FILE=/path/to/axm-token
```

`AXM_TOKEN` remains supported, but a token file is less likely to leak through
process environments. Run `axm help environment` for credential precedence and
the complete automation contract. Never print a token into logs.

### Publishing from GitHub Actions

A GitHub Actions workflow can publish without storing any AgentXM secret. In
[web settings](https://agentxm.ai/u/settings/trusted-publishers), register the
repository and workflow file (and, optionally, its environment) as a trusted
publisher for the extensions you want it to publish. Then grant the job
`id-token: write`:

```yaml
name: Publish extensions
on:
  push:
    tags: ["v*"]

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: release
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v7
      - run: |
          curl -fsSL https://axm.sh/install.sh | sh
          echo "$HOME/.axm/bin" >> "$GITHUB_PATH"
      - run: axm whoami
      - run: axm publish
```

AXM exchanges the job's GitHub Actions ID token for a short-lived workload
token that can do only what the trusted publisher permits. `axm whoami` names
the trusted publisher. If the job lacks `id-token: write` or no trusted
publisher matches it, AXM fails with `auth_required` and says which to fix.
Set `AXM_TRUSTED_PUBLISHING=0` in a job that should not use trusted publishing.

---

## Troubleshooting

### `axm: command not found`

The axm binary is not on your PATH. The fix depends on how you installed it.

**Native Install (macOS/Linux):**

```bash
export PATH="$HOME/.axm/bin:$PATH"
```

Add this line to your shell profile (`~/.profile`, `~/.bashrc`, or `~/.zshrc`), then open a new terminal.

**Native Install (Windows PowerShell):**

```powershell
$env:Path = "$env:USERPROFILE\.axm\bin;" + $env:Path
```

To make it permanent, add `%USERPROFILE%\.axm\bin` to your User PATH via Settings > System > Environment Variables, then open a new terminal.

**Native Install (Windows CMD):**

```cmd
set "PATH=%USERPROFILE%\.axm\bin;%PATH%"
```

To make it permanent, add `%USERPROFILE%\.axm\bin` to your User PATH via Settings > System > Environment Variables, then open a new terminal.

The native installer prints these commands using the resolved install
directory, including custom paths, plus an absolute command for verifying the
installed executable. Automation and non-interactive shells may not load
profile changes, so set PATH explicitly or use that absolute path.

**Homebrew:**

Homebrew should handle PATH automatically. If not, ensure your Homebrew bin directory is on PATH:

```bash
eval "$(brew shellenv)"
```

**npx:**

If `npx` itself is not found, ensure Node.js is installed and its bin directory is on PATH:

```bash
export PATH="$(npm config get prefix)/bin:$PATH"
```

### Authentication errors

**`AUTH_LOGIN_REQUIRED` or "Not authenticated":**

```bash
axm login
# Or for non-interactive environments:
export AXM_TOKEN_FILE=/path/to/axm-token
```

**Wrong account:**

```bash
axm logout && axm login
```

**Token expired:**

Tokens may expire. Re-authenticate:

```bash
axm login
# Or refresh the token:
export AXM_TOKEN_FILE=/path/to/refreshed-axm-token
```