Other

SRAM AXS

axs-pp-cli

Every SRAM AXS feature from the terminal, plus a local database, offline search, and cross-bike views the web app has no way to show.

Printed by @stellato (Greg Stellato)

Install

npx — recommended

npx -y @mvanhorn/printing-press-library install axs

Installs the CLI binary and the agent skill (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more). Add --cli-only or --skill-only for one half. Requires Node.

Hermes

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-axs --force

From the Hermes CLI. Inside a chat session use /skills install with the same path.

OpenClaw

Install the pp-axs skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-axs. The skill defines how its required CLI can be installed.

Paste this to your OpenClaw agent — the skill describes how to install its CLI.

Claude Desktop

This CLI ships an MCPB bundle. Download the latest release .mcpb and double-click it — Claude Desktop walks you through the install.

View source on GitHub →

SRAM AXS CLI for bikes, components, registrations, ride activities, and synced component-summary analytics.

Created by @stellato (Greg Stellato).

Authentication

AXS uses your SRAM account (Auth0). Run axs-pp-cli auth login to sign in with your email and password (handled directly against SRAM's token endpoint — no browser), or paste an access token with axs-pp-cli auth set-token / set SRAM_AXS_TOKEN. The public device-type catalog works with no login.

Quick Start

# check reachability and config before anything else
axs-pp-cli doctor --dry-run

# public catalog — works with no login, proves the API is reachable
axs-pp-cli devicetypes list

# sign in with your SRAM account to unlock your bikes and components
axs-pp-cli auth login

# one-command overview of every bike and component
axs-pp-cli garage

# rank synced component usage from local component summaries
axs-pp-cli wear --json

# read latest synced battery_status per AXS device type
axs-pp-cli battery --json

# total front and rear shifts across synced ride summaries
axs-pp-cli shifts --totals --json

Unique Features

These capabilities aren't available in any other tool for this API.

Synced component-summary views

firmware-check — Show the latest synced firmware version per AXS device type.

Pick this when an agent needs the current synced firmware signal without clicking through every component.
```
axs-pp-cli firmware-check --json
```
battery — Latest synced battery status per AXS device type, including voltage when available.

Pick this for a quick pre-ride battery signal across synced AXS device types.
```
axs-pp-cli battery --json
```

Local state that compounds

wear — Rank components by synced shift counts, distance, and actuations from component summaries.

Use to find the most-used drivetrain component for maintenance planning.
```
axs-pp-cli wear --json --select device_type,device_label,shift_count,fd_shift_count,rd_shift_count
```
shifts — Show per-ride front/rear shift counts, chainrings, and cogs from synced component summaries.

Use for ride-by-ride drivetrain usage analysis without dumping thousands of raw gear samples.
```
axs-pp-cli shifts --totals --json
```
since — Show new ride activities and notifications since your last sync.

Pick this to catch up on what changed without re-reading everything.
```
axs-pp-cli since 7d
```

AXS web data joined for agents

garage — A tree of every bike with its components and serials in one shot.

Use as the one-command overview of a rider's whole AXS setup.
```
axs-pp-cli garage
```

Recipes

Narrow a verbose component list

axs-pp-cli components list --agent --select id,serial,model

Pulls only the high-gravity fields from a component response instead of the full payload.

Register a part safely

axs-pp-cli registrations create --serial ABC123 --dry-run

Shows the registration request without sending it.

Usage

Run axs-pp-cli --help for the full command reference and flag list.

Commands

account

Your SRAM account profile and settings

axs-pp-cli account accessgroups - Get your public access groups
axs-pp-cli account export - Request a data export of your account
axs-pp-cli account flags - Get your account feature flags
axs-pp-cli account profile - Get your account profile

activities

Your ride activities (telemetry host)

axs-pp-cli activities list - List your ride activities
axs-pp-cli activities types - List activity types

bikes

Your registered bikes

axs-pp-cli bikes get - Get a bike by ID
axs-pp-cli bikes list - List your registered bikes

components

Your AXS components (derailleurs, shifters, batteries, dropper posts)

axs-pp-cli components get - Get a component by ID
axs-pp-cli components list - List your AXS components

devicetypes

Catalog of AXS device types (public, no login required)

axs-pp-cli devicetypes - List all AXS device types

linkedids

Linked third-party accounts (Strava, etc.)

axs-pp-cli linkedids list - List your linked third-party accounts
axs-pp-cli linkedids unlink - Unlink a third-party account

models

Catalog of component models and their firmware versions

axs-pp-cli models - List component models and latest firmware versions

notifications

Your notifications inbox

axs-pp-cli notifications - List your notifications

products

Product detail lookups

axs-pp-cli products <id> - Get product detail by product ID

registrations

axs-pp-cli registrations - Register a component to your account by serial number

stats

Aggregate account stats (telemetry host)

axs-pp-cli stats - Get your aggregate riding stats

summaries

Activity and component usage summaries (telemetry host)

axs-pp-cli summaries activities - List per-activity summaries
axs-pp-cli summaries components - List component usage summaries (wear, shift counts, distance)

units

Measurement / advanced units catalog

axs-pp-cli units - List advanced measurement units

Output Formats

# Human-readable table (default in terminal, JSON when piped)
axs-pp-cli activities list

# JSON for scripting and agents
axs-pp-cli activities list --json

# Filter to specific fields
axs-pp-cli activities list --json --select id,name,status

# Dry run — show the request without sending
axs-pp-cli activities list --dry-run

# Agent mode — JSON + compact + no prompts in one flag
axs-pp-cli activities list --agent

Agent Usage

This CLI is designed for AI agent consumption:

Non-interactive - never prompts, every input is a flag
Pipeable - --json output to stdout, errors to stderr
Filterable - --select id,name returns only fields you need
Previewable - --dry-run shows the request without sending
Explicit retries - add --idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
Confirmable - --yes for explicit confirmation of destructive actions
Piped input - write commands can accept structured input when their help lists --stdin
Offline-friendly - sync/search commands can use the local SQLite store when available
Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

axs-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/axs-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
`SRAM_AXS_TOKEN`	per_call	Yes	Set to your API credential.

agentcookie (optional)

If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, axs-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.

Troubleshooting

Authentication errors (exit code 4)

Run axs-pp-cli doctor to check credentials
Verify the environment variable is set: echo $SRAM_AXS_TOKEN Not found errors (exit code 3)
Check the resource ID is correct
Run the list command to see available items

API-specific

401 Authentication credentials were not provided — Run axs-pp-cli auth login or set SRAM_AXS_TOKEN to a valid access token.
Token expired — Run axs-pp-cli auth login again; access tokens are short-lived.
Empty bikes/components after login — Run axs-pp-cli sync to populate the local mirror, then retry.

Known Gaps

No firmware flashing / BLE control. This CLI can read account, activity, and synced component-summary data exposed to AXS web clients. Updating firmware, pairing components, or changing shift behavior still happens over Bluetooth in the SRAM AXS phone app and is out of scope.