flywheel setup CLI

This package configures Flywheel MCP for supported AI coding hosts and can install or refresh all bundled Flywheel skills during setup.

Public Guided Install (Primary Human Flow)

npx --yes @paradigma-inc/flywheel setup

Guided flow:

1. Flywheel MCP setup runs first.
2. If at least one selected host supports bundled skill install, setup asks one of these prompts:
   • Also install or refresh the bundled Flywheel skill?
   • Also install or refresh the bundled Flywheel skills?
3. The prompt default is yes.

If you accept the default, the run completes with MCP plus bundled skill setup for supported hosts.

Public Base URL Rules

--base-url must be a public Flywheel origin, not a backend URL and not a URL with a path/query/fragment.

Use public origins such as:

• https://flywheel.paradigma.inc

Do not pass backend Fly machine hostnames (for example *.fly.dev) to --base-url.

Explicit Automation Flows

Prompt-free combined MCP plus skill setup:

npx --yes @paradigma-inc/flywheel setup --install-skill

Prompt-free MCP-only setup:

npx --yes @paradigma-inc/flywheel setup --skip-skill

--install-skill and --skip-skill are mutually exclusive.

Non-interactive setup requires one of those flags.

Auth Modes And Remote Shells

setup --auth-mode auto|loopback|device controls authentication behavior:

• loopback: opens /auth/mcp/setup and waits for a localhost callback.
• device: opens /auth/mcp/setup/device, confirms a setup code in browser, and CLI polls for approval.
• auto (default): uses device on SSH shells and loopback otherwise.

Remote/headless example:

npx --yes @paradigma-inc/flywheel setup \
  --auth-mode device \
  --base-url https://flywheel.paradigma.inc

Scope Rules

• Default scope (no --project) is user-level/global: MCP config is written to the host's global config path and bundled skill install targets user-level skill directories.
• --project is the explicit repo-local override: MCP config and bundled skill install both target project-local paths.

Examples:

# Global default
npx --yes @paradigma-inc/flywheel setup --install-skill --codex --api-key <token>

# Project-local override
npx --yes @paradigma-inc/flywheel setup --install-skill \
  --project --codex --api-key <token>

Public Update Flow

After a new release:

• Human-guided update:

npx --yes @paradigma-inc/flywheel@latest setup

• Automation update:

npx --yes @paradigma-inc/flywheel@latest setup --install-skill

Reruns refresh every already-installed bundled skill in place and install any newly bundled skills from the updated package. They do not create side-by-side copies for the same scope and agent location.

If you choose to refresh via skills experimental_sync instead of rerunning setup, install Flywheel locally in that project first:

npm install --save-dev @paradigma-inc/flywheel@latest
npx skills experimental_sync --agent codex -y

Supported Hosts For Bundled Skill Install

• Claude Code
• Codex
• OpenCode
• Cursor
• OpenClaw
• Pi (pi-mono)

Hermes Agent remains MCP-only in phase 1.

Troubleshooting

Advanced troubleshooting (optional): inspect installed skill state directly. Normal users do not need to run these commands for install/update.

npx --yes skills ls -a codex
npx --yes skills ls -a claude-code
npx --yes skills ls -a cursor

If any bundled skill is missing, rerun setup using either guided setup or explicit setup --install-skill.

Other Commands

• setup: guided setup-centric flow.
• uninstall: removes Flywheel MCP entries from host configs only.

npx --yes @paradigma-inc/flywheel uninstall

• npx --yes only auto-confirms npx; it does not imply flywheel --yes.