Stratos

stratos

Official command-line client and Node ESM library for CloudCDN — the full control plane in a single ~4,000-line, zero-dependency Node ≥ 20 script.

---

Contents

Getting started

• [Install](#install) — eight channels, SHA-pinned installer
• [Quick Start](#quick-start) — verify, authenticate, purge in five lines
• [Why a single-file CLI?](#why-a-single-file-cli) — design rationale

Companion artefacts

• [Companion artefacts](#companion-artefacts) — composite GitHub Action, MCP server, Docker image
• [Migrating from another CDN CLI](#migrating-from-another-cdn-cli) — Wrangler, Fastly CLI, Codex CLI

CLI reference

• [Capabilities](#capabilities) — release inventory
• [Authentication & profiles](#authentication--profiles) — env, profile, keychain
• [Commands](#commands) — full command table
• [Programmatic API](#programmatic-api) — drive Stratos in-process
• [MCP server](#mcp-server) — agent integration
• [Machine-readable schema](#machine-readable-schema) — stratos schema
• [Output, exit codes, typed errors](#output-exit-codes-typed-errors) — pipeline contract

Operational

• [Examples](#examples)
• [When not to use Stratos](#when-not-to-use-stratos)
• [Integrity & supply chain](#integrity--supply-chain)
• [Development](#development)
• [Tests & coverage](#tests--coverage)
• [Release pipeline](docs/release-pipeline.md)
• [Security](#security)
• [Governance](#governance)
• [Documentation](#documentation)
• [License](#license)

---

Install

Stratos ships as one ES module (stratos.mjs, ~4,000 lines, zero runtime dependencies). Eight distribution channels:

| Channel | Command | |---|---| | npm (recommended) | npm install -g @cloudcdn/stratos | | Homebrew (macOS / Linux, no Node required) | brew tap sebastienrousseau/tap && brew install sebastienrousseau/tap/stratos | | winget (Windows) | winget install CloudCDN.Stratos | | Scoop (Windows) | scoop bucket add sebastienrousseau https://github.com/sebastienrousseau/scoop-bucket && scoop install stratos | | Single binary (no Node required) | Download from the latest release — stratos-{linux-x64,linux-arm64,darwin-x64,darwin-arm64,win-x64.exe}. Compiled with Bun; ~58 MB, ~20 ms cold start. | | macOS / Linux installer | curl -sL https://cloudcdn.pro/dist/stratos/install.sh \| bash | | Windows (PowerShell) | irm https://cloudcdn.pro/dist/stratos/install.ps1 \| iex | | From source | git clone https://github.com/sebastienrousseau/stratos && cd stratos && node stratos.mjs help |

Override the installer prefix:

curl -sL https://cloudcdn.pro/dist/stratos/install.sh | STRATOS_PREFIX=$HOME/bin bash

Both shell installers verify a pinned SHA-256 of the script before writing it to disk. npm releases are published with Sigstore-backed provenance — verify with npm audit signatures. Every release also ships a SLSA L3 build provenance attestation (stratos-v.intoto.jsonl) and a Cosign keyless signature for each canonical artefact — see [Integrity & supply chain](#integrity--supply-chain).

> Module format: @cloudcdn/stratos is ESM only ("type": "module"). Modern Node ≥ 20 consumes it directly with import. CommonJS callers use dynamic import: const stratos = await import('@cloudcdn/stratos').

---

Quick Start

# Verify the install
stratos version
# → stratos v0.0.17

# Hit the public health endpoint
stratos health
# → { "status": "ok", "bindings": { "ai": true, "kv": true, "d1": true, "r2": true } }

# Set up tab completion (zsh shown; bash/fish/powershell also supported)
eval "$(stratos completion zsh)"

# Authenticate once, then drive the control plane
export CLOUDCDN_ACCOUNT_KEY="cdnsk_…"
stratos purge https://cloudcdn.pro/akande/v1/logos/logo.svg
stratos purge --tag "build-${GITHUB_SHA}" --tag project-akande
cat urls.txt | stratos purge -      # batch invalidate from stdin

# Stream NDJSON into jq for downstream pipelines
stratos assets --all --output ndjson | jq -r '.Path'

# Introspect the surface (agent caller's gateway)
stratos schema --output ndjson | jq -r 'select(.mcp_tool) | "\(.name) → \(.mcp_tool)"'

In-terminal demos

| Command | Cast | |---|---| | stratos purge --tag … --dry-run | | | stratos signed … (offline HMAC mint) | | | stratos doctor | |

> Re-record any cast with node scripts/make-casts.mjs --render — needs agg (brew install agg).

---

Why a single-file CLI?

Most edge-platform CLIs ship as 30–80 MB Node bundles with hundreds of transitive dependencies. Stratos takes a deliberately different bet:

• One file — stratos.mjs is the entire CLI. No build step. No transpiler. The thing that runs is the thing you read.
• Zero runtime dependencies — only Node ≥ 20 standard library. No transitive supply-chain exposure. Zero node_modules in the install footprint.
• One SHA-pin — installers verify a single SHA-256 of the script before touching disk. Tampered CDN responses fail the check before anything is executed.
• Cold-start under 70 ms on M-series — measured by stratos bench. Suitable for CI hot loops and shell pipelines.
• Errors to stderr, machine output to stdout — pipelines like stratos assets --output ndjson | jq … stay clean.
• Sysexits-style exit codes and stable typed errors — make and shell || chains can branch on cause (64 USAGE, 77 NOPERM, 75 TEMPFAIL, …); agents drive backoff loops from error.type and error.retryable.
• CLI is also a library — every command is an exported ESM function; the test suite drives it in-process and you can too.

If those trade-offs match what you need, read on. If you'd prefer a richer SDK with a build pipeline, see [When not to use Stratos](#when-not-to-use-stratos).

---

Companion artefacts

Three artefacts ship from this repo. The CLI is the core; the others wrap it for specific delivery surfaces.

| Artefact | What it is | Use case | |---|---|---| | @cloudcdn/stratos | The CLI and library (this README) | Local terminal, CI, scripts, in-process integration | | sebastienrousseau/stratos/actions/stratos@v | Composite GitHub Action | Drop-in CI step; auto-detects GITHUB_ACTIONS, emits ::error:: workflow commands on non-zero exit. See [actions/stratos/README.md](actions/stratos/README.md). | | stratos mcp serve | Model Context Protocol stdio server (bundled) | Claude Code, Cursor, Continue.dev, Zed assistant, any MCP host — see [MCP server](#mcp-server) | | ghcr.io/sebastienrousseau/stratos | Multi-arch Docker image (linux/amd64, linux/arm64) | Containerised CI runners; docker run --rm ghcr.io/sebastienrousseau/stratos:latest version |

---

Migrating from another CDN CLI

Three step-by-step guides covering the equivalent commands, authentication mapping, and behavioural differences:

| Coming from… | Guide | |---|---| | Cloudflare Wrangler | [examples/migrate-from-wrangler.md](examples/migrate-from-wrangler.md) | | Fastly CLI | [examples/migrate-from-fastly.md](examples/migrate-from-fastly.md) | | OpenAI Codex CLI (agentic-CLI patterns) | [examples/migrate-from-codex.md](examples/migrate-from-codex.md) |

> Agent harnesses can introspect Stratos's full verb + error surface in one call via stratos schema --output ndjson — no --help parsing required. See [Machine-readable schema](#machine-readable-schema).

---

Capabilities

Stratos covers ~35 commands across the full CloudCDN platform, grouped by concern.

| Theme | Capabilities | |---|---| | Edge cache | URL / Cache-Tag / wildcard purge, dry-run preview, stdin batching, offline length-prefixed HMAC-SHA256 signed URLs | | Catalog & analytics | Paginated asset catalogue with --all auto-walk, per-asset metadata, insights (summary, top, asset, errors, geo), audit logs, raw analytics filter | | Multi-tenancy | Zone create / list / show / delete, custom-domain attachment | | Config-as-code | _headers / _redirects get / set / LCS-based diff (exits non-zero on drift, git-style) | | Auth & secrets | Scoped API tokens, webhook subscriptions, stratos login → OS keychain (macOS security, libsecret, Windows cmdkey) | | Storage | Single-file CRUD plus recursive sync over the batch endpoint, 50 files / request | | Observability | SSE-streamed live logs tail, historical logs query, doctor env diagnostic, bench cold-start + latency sampler, OTLP/HTTP tracing via --otlp-endpoint (one span per command) | | AI & media | Alt-text, moderation, smart-crop, background-remove; on-the-fly image transform, BlurHash, LQIP, format negotiation, HLS playlist builder | | Pipeline & discovery | SVG-driven asset scaffolding, hybrid vector + fuzzy search, AI concierge (ask) | | Agent integration | stratos mcp serve (10 tools / 6 resources / 4 prompts), stratos schema machine-readable command catalogue, --output ndjson streaming, stable typed errors (error.type + retryable) | | Operator UX | Shell completions (bash/zsh/fish/PowerShell), XDG-compliant profiles, --json, --output ndjson\|yaml\|csv\|table, --filter , -q, --verbose, --rate /s client-side throttle, configurable --timeout / --retries with full-jitter backoff |

---

Authentication & profiles

Configuration is resolved from four sources, highest precedence first:

1. Per-command flags — --account-key, --access-key, --cdn-url, --secret, --timeout, --retries, --profile.
2. Environment variables — see table below.
3. Profile file — ~/.config/stratos/config.json (XDG-compliant), selected with --profile or $STRATOS_PROFILE.
4. OS keychain — populated via stratos login; suppressed by STRATOS_NO_KEYCHAIN=1.

| Env var | Purpose | Default | |---|---|---| | CLOUDCDN_URL | API base URL | https://cloudcdn.pro | | CLOUDCDN_ACCOUNT_KEY | Control plane: purge, zones, rules, tokens, webhooks | unset | | CLOUDCDN_ACCESS_KEY | Read-only: assets, insights, search | unset | | SIGNED_URL_SECRET | HMAC secret for signed (offline) | unset | | STRATOS_PROFILE | Default profile name | default | | CLOUDCDN_TIMEOUT | Per-request timeout, ms | 15000 | | CLOUDCDN_RETRIES | Max retries on 429 / 5xx / network | 3 | | STRATOS_NO_KEYCHAIN | Set to 1 to skip OS-keychain lookups | unset | | OTEL_EXPORTER_OTLP_ENDPOINT | OTLP/HTTP traces endpoint (alt to --otlp-endpoint) | unset | | OTEL_EXPORTER_OTLP_HEADERS | OTLP exporter headers (k=v,k=v) | unset | | NO_COLOR | Set to disable ANSI output | unset |

Profile setup is round-trippable via stratos config:

stratos config set prod.url        https://cloudcdn.pro
stratos config set prod.account_key cdnsk_xxx…
stratos config set staging.url     https://staging.cloudcdn.example
stratos config list

# Then everywhere:
stratos --profile prod purge --tag build-123
STRATOS_PROFILE=staging stratos health --deep

The config file is written with permission mode 0600.

For the most secure setup, store keys in the OS keychain instead:

stratos login              # interactive prompt; writes to macOS Keychain / libsecret / cmdkey
stratos login status       # show resolved config with secrets masked
stratos logout             # clear all stratos secrets from the keychain

---

Commands

Edge ops

| Command | What it does | |---|---| | version, -v, --version | Print version | | help [], -h, --help | Print help; per-command --help too | | health [--deep] | GET /api/health (add ?deep=1 with --deep) | | purge ... | Invalidate by URL | | purge --tag ... | Invalidate by Cache-Tag (repeats accumulate) | | purge --everything | Wipe edge cache (hard-rate-limited) | | purge --dry-run | Preview the payload without sending | | purge - | Read URLs from stdin (one per line) | | signed --expires [--secret ] | Offline length-prefixed HMAC-SHA256 URL |

Catalog & insights

| Command | What it does | |---|---| | assets [--project] [--format] [--page] [--all] | Paginated catalogue; --all walks every page (cap: 1,000) | | assets show | Single-asset metadata | | insights summary [--days N] [--zone Z] | Requests, bandwidth, cache ratio | | insights top [--limit N] [--days N] | Top requested assets | | insights asset [--days N] | Per-asset traffic | | insights errors [--days N] | 4xx / 5xx breakdown | | insights geo [--days N] | Country distribution | | stats [--days N] [--zone Z] | /api/core/statistics | | analytics query [...] | /api/analytics filter | | audit [--action A] [--days N] | Immutable audit trail |

Zones, rules, tokens, webhooks

| Command | What it does | |---|---| | zones list \| create \| show \| rm --force | Tenant zones | | zones domains add | Add a custom domain | | rules get | Read the edge config file | | rules set -f | Write it back via Git | | rules diff -f | LCS line diff; exits 0 if identical, 69 on drift | | tokens list \| create --name N --scopes S,S \| rm | Scoped API tokens | | webhooks list \| add --url U --events E,E \| rm | Event subscriptions |

Storage

| Command | What it does | |---|---| | storage put | Single-file upload | | storage get [] | Download (stdout if no `) | | storage rm | Delete | | storage ls | List under a prefix | | storage sync | Recursive upload via /api/storage/batch` (50 / req) |

AI, image, media

| Command | What it does | |---|---| | ai alt \| moderate \| crop \| bg-remove | AI vision endpoints | | image transform [--w --h --fit --format --q --blur --sharpen] | Resize / convert | | image blurhash [--size N] | BlurHash placeholder | | image lqip [--size N] [--blur N] | Tiny blurred placeholder | | image auto | Format negotiation | | stream [--quality Q] [--segment N] | HLS playlist or segment URL |

Pipeline & discovery

| Command | What it does | |---|---| | pipeline submit --svg --name N | Asset scaffold from an SVG | | search [--limit N] | Hybrid asset search | | ask | CloudCDN AI concierge | | logs tail [--level L] | SSE-stream live logs | | logs query [--days N] [--level L] [--limit N] | Historical logs |

Meta

| Command | What it does | |---|---| | init | Interactive first-run setup; scriptable via flags | | schema [--output json\|ndjson\|yaml] | Machine-readable command catalogue (drives MCP tool registration, completion, doc generation) | | completion | Emit completion script | | upgrade | Re-run the latest pinned installer | | config get \| set \| list \| edit | Profile management; edit opens $EDITOR | | login / login status / logout | Store keys in the OS keychain | | passkey | WebAuthn ceremony bootstrapper (browser) | | doctor | Diagnose env, credentials, network | | bench [-n N] | Cold-start + N latency samples | | explain | Cause + fix for an exit code or HTTP status | | mcp serve | Run as an MCP server over stdio (10 tools, 6 resources, 4 prompts) |

Global options

--json (force JSON), --no-json (opt out of CI auto-JSON), --output (json / ndjson / yaml / csv / table; jsonl is an alias for ndjson), --filter (pipe output through jq), -q / --quiet (suppress info), --no-quiet (opt out of CI auto-quiet), --verbose (trace requests), --profile , --cdn-url , --account-key , --access-key , --timeout , --retries , --rate [/s] (client-side rate limit for bulk ops), --otlp-endpoint , --otlp-headers k=v,k=v.

When CI is detected (GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, JENKINS_URL, TF_BUILD, or CI=true), Stratos auto-enables --json --quiet and, on GitHub Actions, emits ::error:: workflow commands on non-zero exit so failures surface inline on PR/run

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sebastienrousseau
• Source: sebastienrousseau/stratos
• License: MIT
• Homepage: https://cloudcdn.pro/dist/stratos/

Install and usage instructions live in the source repository linked above.