Alltrails Unofficial Seed CLI

Evidence-labeled, live-capable route map for AllTrails browser/mobile surfaces. Not an official API contract.

Learn more at Alltrails.

Created by @zaydiscold (zaydiscold).

Quick Start

1. Install

See Install above.

2. Configure Auth

Public reads may work without credentials, but account routes need caller-owned AllTrails auth:

export ALLTRAILS_ACCESS_TOKEN="..."
# or
export ALLTRAILS_COOKIE="..."
export ALLTRAILS_CSRF_TOKEN="..." # only for browser-backed writes that require CSRF

3. Verify Setup

alltrails-pp-cli doctor

This checks your configuration.

4. Try Your First Command

alltrails-pp-cli alltrails list

Usage

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

Commands

alltrails

Manage alltrails

• alltrails-pp-cli alltrails create - Upload a new activity recording
• alltrails-pp-cli alltrails get - Activity detail with GPS/stat surfaces
• alltrails-pp-cli alltrails get-v3 - Trail detail payload
• alltrails-pp-cli alltrails get-v3-2 - Offline map metadata
• alltrails-pp-cli alltrails get-v3-3 - Map static image metadata/render endpoint
• alltrails-pp-cli alltrails get-v3-4 - Trail static map image metadata/render endpoint
• alltrails-pp-cli alltrails get-v3-5 - User activity list
• alltrails-pp-cli alltrails list - Trail search by text, location, and filters
• alltrails-pp-cli alltrails list-v3 - Current account profile

Output Formats

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

# JSON for scripting and agents
alltrails-pp-cli alltrails list --json

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

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

# Write routes default to dry-run; live writes require both controls
ALLTRAILS_PP_ALLOW_WRITES=1 alltrails-pp-cli alltrails create --live-write --stdin < activity.json

# Agent mode — JSON + compact + no prompts in one flag
alltrails-pp-cli alltrails 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 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, 5 API error, 7 rate limited, 10 config error.

Health Check

alltrails-pp-cli doctor

Verifies configuration and connectivity to the API.

Configuration

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

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

Auth Environment

• ALLTRAILS_ACCESS_TOKEN sets an Authorization: Bearer ... header.
• ALLTRAILS_COOKIE sets the browser Cookie header for authenticated AllTrails routes.
• ALLTRAILS_CSRF_TOKEN sets x-csrftoken for browser-backed write routes when needed.

Write Safety

Reads run without a write gate. Any non-read route is labeled with pp:risk and mcp:risk, defaults to --dry-run in the CLI unless --live-write is passed, and is blocked at the HTTP transport unless ALLTRAILS_PP_ALLOW_WRITES=1 is present. MCP write tools also default to dry-run unless the same env gate is set.

See docs/write-operations.md for the exact live-write contract.

Sync

AllTrails browser APIs are DataDome-protected outside the logged-in browser context, so sync defaults to a safe no-op. To try a resource explicitly, pass --resources routing_info with caller-owned auth/cookies configured.

Troubleshooting

Not found errors (exit code 3)

• Check the resource ID is correct
• Run the list command to see available items

HTTP Transport

This CLI uses standard Go HTTP transport with HTTP/2 enabled when AllTrails negotiates it. It does not require a resident browser process for normal API calls.

---

Generated by CLI Printing Press