AXIS CLI

Name: HOOX
Author: HOOX

packages/cli — install, doctor, Worker setup (D1/OAuth), secrets, deploy, health — CLI-first operator path.

This page

Manuals

Section PDFDevOps Full PDFComplete

AXIS CLI

Abstract

The AXIS CLI (@hoox-sh/axis-cli under packages/cli) is the CLI-first operator entry for local install, Worker bootstrap, Cloudflare® secrets, deploy, and health checks. It wraps Bun + Wrangler with AXIS-specific paths and defaults (Worker name worker-axis, D1 pynescript, OAuth device flow).

axis --help listing install, doctor, setup, deploy, health

Requires Node ≥ 20 to run the published binary (npm i -g @hoox-sh/axis-cli) and Bun ≥ 1.2 for install/dev/build commands that shell out to Bun. Product version follows root package.json; the CLI package (@hoox-sh/axis-cli) is versioned independently and publishes on v* tags via .github/workflows/release.yml.

Conceptual model

Diagram

Rendering…

Install

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

# from monorepo root
bun install
cd packages/cli && bun install && bun run build && cd ../..

bun run axis --help
# Make pass-through
make axis ARGS="--help"
# Optional global link
cd packages/cli && bun link && axis --help

Repo aliases (bun scripts & Make targets)

axis is the primary interface. These aliases exist for working inside the repo checkout without a global install:

Alias	Runs
`bun run axis -- <args>`	`packages/cli/bin/axis.js`
`bun run axis:install`	`axis install`
`bun run axis:doctor`	`axis doctor`
`bun run axis:setup`	`axis setup`
`bun run axis:deploy`	`axis deploy` (default worker)
`bun run axis:health`	`axis health`
`make axis ARGS="doctor --remote"`	same bin with args
`make axis-install` · `axis-doctor` · `axis-setup` · `axis-deploy` · `axis-health`	fixed wrappers

When using bun run axis setup -- --flag, keep the -- so Bun forwards flags to the CLI.

Command surface

Command	Role
`axis install`	`bun install` root + `worker/` + CLI
`axis doctor` [`--remote`]	Toolchain, CF auth, optional live `/health`. Missing `worker/wrangler.toml` is a warning until `axis setup` (expected on a fresh clone).
`axis setup`	Bootstrap: install → ensure toml → local D1
`axis setup --prod`	Production bootstrap: remote D1 schema + `API_KEYS` KV
`axis setup worker`	Copy `wrangler.toml.example` → `wrangler.toml` if missing
`axis setup d1 --local\|--remote` [`--create`]	Apply `worker/schemas/scripts.sql` (scripts + version history)
`axis setup kv [--usage]`	Create and bind `API_KEYS` KV (required when D1 is on)
`axis setup oauth --github-client-id …`	Set public OAuth App id in `[vars]` (or `--secret`)
`axis keys create [--tier hobby]`	Mint a `pn_…` key via `POST /api/keys` (`ADMIN_TOKEN`)
`axis keys validate --key pn_…`	Validate a key against the Worker
`axis secret put\|list\|delete`	Wrangler secrets (`ADMIN_TOKEN`, `EXTERNAL_BACKEND`, …)
`axis deploy` / `deploy worker`	Apply remote D1 schema, then deploy Worker `worker-axis`
`axis deploy pages`	Vite build + Pages project
`axis deploy all`	Schema + Worker + Pages
`axis health [--oauth] [--scripts] [--url …]`	Probe `/health`, optional OAuth start, optional `/api/scripts`
`axis whoami`	Cloudflare® account
`axis dev`	Vite product UI
`axis dev worker`	Local wrangler Worker
`axis dev desktop`	Tauri desktop shell

Global flags: --json, --quiet, -y / --yes.

Installation self-check

Every axis command starts with a lightweight, local-only self-check (skipped for --version / --help, silenced by --quiet / --json). It never blocks a command — it only prints stderr warnings when something is off:

Runtime compliance vs engines (Node ≥ 20, Bun ≥ 1.2)
Install context — npm install, npx cache, or repo checkout
Version drift — a globally installed CLI older than the repo checkout it is operating on (npm i -g @hoox-sh/axis-cli to update)

The same check appears as the optional CLI installation row in axis doctor (and in doctor --json as cli-install).

axis doctor: required toolchain and wrangler checks passed

Production checklist

axis install
axis doctor
axis setup --prod --github-client-id Ov23li…
axis secret put ADMIN_TOKEN   # comments empty [vars] ADMIN_TOKEN, deploys, then sets secret
axis secret put EXTERNAL_BACKEND
axis deploy all
axis keys create              # --admin-token / AXIS_ADMIN_TOKEN / prompt
axis health --scripts --oauth
# Paste Worker URL + pn_… into Settings → Script storage

Item	Guidance
`GITHUB_OAUTH_CLIENT_ID`	Public OAuth App id; Device Flow enabled on GitHub; env wins over body `clientId`
`GITLAB_OAUTH_CLIENT_ID`	Same for GitLab when using git storage
`ADMIN_TOKEN` / `EXTERNAL_BACKEND`	Prefer `axis secret put`. An empty `[vars]` stub collides with secrets (Cloudflare 10053)
`API_KEYS` KV	`axis setup kv` then `axis deploy worker`. D1 without KV fails closed (`API_KEYS_REQUIRED`)
`ALLOW_OPEN_KEYS`	`"0"` in production
`REQUIRE_RUN_AUTH`	`"1"` to force Bearer on `/api/run` even without KV
Worker script	`worker-axis` (`https://worker.axis.hoox.sh`)
Pages project	`axis` (`https://axis.hoox.sh`)

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`
`CLOUDFLARE_API_TOKEN`	Non-interactive Wrangler auth
`AXIS_CLI_SRC=1`	Load `src/` instead of `dist/`

Internals

Path	Role
`packages/cli/bin/axis.js`	Bin entry (Bun)
`packages/cli/src/commands/*`	Commander handlers (`install`, `doctor`, `setup`, `keys`, `deploy`, `secrets`, `health`, `dev`, `whoami`)
`packages/cli/src/services/wrangler-toml.ts`	Toml vars, D1 id, KV binding upsert
`packages/cli/src/services/health.ts`	`/health` + OAuth probes
Root `package.json` `axis` / `axis:*` scripts	Convenience wrappers
Root `Makefile` `axis` / `axis-*`	Make wrappers