Skip to content

README.md

Latest commit

 

History

History
118 lines (92 loc) · 5.24 KB

README.md

File metadata and controls

118 lines (92 loc) · 5.24 KB
Raw

@hoox-sh/axis-cli

AXIS CLI — install flows, doctor, Worker setup (D1 / KV / keys), secrets, deploy, and health probes for the AXIS charting PWA.

Requires Node ≥ 20 to run the published binary, and Bun ≥ 1.2 for axis install / axis dev / axis deploy pages (those shell out to Bun).

axis --help

Install

# npm (global)
npm install -g @hoox-sh/axis-cli
axis --help

# standalone binary (single file, no Node/Bun required)
# download axis-cli-<cli-version>-bun-<target> from the release assets:
#   bun-linux-x64 | bun-linux-arm64 | bun-linux-x64-musl | bun-linux-arm64-musl
#   bun-darwin-x64 | bun-darwin-arm64 | bun-windows-x64.exe
# Release tag = app VERSION (v2.7.0). Filename uses CLI package version (0.3.3).
curl -LO "https://github.com/hoox-sh/axis/releases/download/v2.7.0/axis-cli-0.3.3-bun-linux-x64"
chmod +x axis-cli-0.3.3-bun-linux-x64 && ./axis-cli-0.3.3-bun-linux-x64 --version

# from the AXIS monorepo
bun install
cd packages/cli && bun install && bun run build && cd ../..
bun packages/cli/bin/axis.js --help

Build the binaries yourself: cd packages/cli && bun run build:binaries (bun --compile cross-builds every target; native output is smoke-tested).

CLI-first — install once, call axis anywhere:

axis --help
axis doctor

Repo aliases (no global install): bun run axis --help · bun run axis:doctor — see root package.json scripts.

Global flags: --json, --quiet, -y/--yes. --json is machine-only (no banners mixed into stdout).

Commands

Command Purpose
axis install bun install for app, worker/, and CLI
axis doctor Toolchain + optional Cloudflare auth. Missing worker/wrangler.toml warns until axis setup (expected on a fresh clone).
axis doctor --remote Also probe deployed Worker /health
axis setup Full bootstrap (install → toml → local D1)
axis setup --prod Production bootstrap: remote D1 schema + API_KEYS KV
axis setup worker Ensure worker/wrangler.toml (copy from example)
axis setup d1 [--local] [--remote] [--create] Apply schemas/scripts.sql (scripts + versions)
axis setup kv [--usage] Create and bind API_KEYS KV (required when D1 is on)
axis setup oauth --github-client-id Ov23li… Set OAuth client id in [vars]
axis setup oauth --github-client-id … --secret Or as Worker secret
axis keys create [--tier hobby] Mint a pn_… key (ADMIN_TOKEN required)
axis mcp [--key pn_…] Stdio MCP proxy to Worker POST /mcp
axis mcp config Print MCP client JSON (remote URL or --stdio)
axis keys validate --key pn_… Validate a key against /api/keys
axis secret put ADMIN_TOKEN wrangler secret put
axis secret list / axis secret delete <name> List / delete secrets
axis deploy / axis deploy worker Deploy Worker worker-axis
axis deploy pages Vite build + Pages project
axis deploy all Worker then Pages
axis health [--oauth] [--scripts] [--url …] Probe /health (+ OAuth start and/or /api/scripts)
axis whoami Cloudflare account
axis dev / axis dev worker / axis dev desktop Local servers

axis doctor: required checks passed

Typical production flow

axis install
axis doctor
axis setup --prod --github-client-id Ov23liekgk16zDDiHBz1
axis secret put ADMIN_TOKEN        # comments empty [vars] stub, deploys, sets secret
axis secret put EXTERNAL_BACKEND   # public HTTPS PYNE/Flask base
axis deploy all                    # applies D1 schema, then Worker + Pages
axis keys create                   # --admin-token / AXIS_ADMIN_TOKEN / prompt
axis health --scripts --oauth

axis setup --prod is --remote-d1 plus API_KEYS KV create/bind. axis deploy / deploy all apply the remote D1 schema first (--skip-schema to skip). axis setup d1 --remote is remote-only; pass both --local --remote to apply both.

Env overrides:

Variable Role
AXIS_ROOT Force monorepo root
AXIS_WORKER_URL Default health/deploy probe URL
AXIS_ADMIN_TOKEN Admin token for axis keys create
AXIS_API_KEY Default key for axis keys validate / health --scripts --key / axis mcp
CLOUDFLARE_API_TOKEN Wrangler auth (non-interactive)
AXIS_CLI_SRC=1 Force bin to load src/ over dist/ (Bun only)

MCP

Remote MCP on the Worker (POST /mcp). Same Bearer key as cloud scripts.

axis mcp config --key pn_…                 # JSON for Cursor / Inspector
axis mcp config --stdio --key pn_…         # spawn `axis mcp` from a local client
axis mcp --key pn_…                        # stdio JSON-RPC → Worker
# AXIS_API_KEY / AXIS_WORKER_URL also apply

Point the client at https://worker.axis.hoox.sh/mcp with Authorization: Bearer pn_…. App-plane tools (app_invoke) need an AXIS tab with Settings → MCP connected. Docs: MCP (agents) · MCP server.

License

AGPL-3.0-only · jango_blockchained