flywheel setup CLI

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

@paradigma-inc/flywheel is the only user-facing Flywheel CLI install path and owns the public flywheel binary surface.

Install

One-shot installer (macOS and Linux):

curl -fsSL https://flywheel.paradigma.inc/install | sh

The script installs @paradigma-inc/flywheel@latest into the managed user prefix ${FLYWHEEL_INSTALL_PREFIX:-$HOME/.local}, adds a marked PATH block when needed, and then runs guided flywheel setup through the installed binary. In an interactive terminal, setup asks whether you want MCP host setup or CLI-only setup. You can read the full source at the same URL without piping to sh.

Prefer the two-step npm recipe? It still works:

# --mode cli: direct flywheel command setup without MCP host wiring
FLYWHEEL_INSTALL_PREFIX="${FLYWHEEL_INSTALL_PREFIX:-$HOME/.local}"
npm install -g --prefix "$FLYWHEEL_INSTALL_PREFIX" @paradigma-inc/flywheel@latest
export PATH="$FLYWHEEL_INSTALL_PREFIX/bin:$PATH"
"$FLYWHEEL_INSTALL_PREFIX/bin/flywheel" setup --mode cli

Persist that PATH line in your shell profile if you use the manual recipe; the curl installer does this idempotently with a marked Flywheel-owned block.

On Windows (PowerShell), use a user-owned prefix:

$prefix = "$env:USERPROFILE\.local"
npm install -g --prefix $prefix @paradigma-inc/flywheel@latest
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if (($userPath -split ";") -notcontains $prefix) {
  $nextUserPath = if ($userPath) { "$prefix;$userPath" } else { $prefix }
  [Environment]::SetEnvironmentVariable("Path", $nextUserPath, "User")
}
if (($env:Path -split ";") -notcontains $prefix) {
  $env:Path = "$prefix;$env:Path"
}
& "$prefix\flywheel.cmd" setup --mode cli

Configure your AI host (Claude Code, Codex, etc.) to call Flywheel over MCP:

# --mode mcp — your AI host calls Flywheel over MCP
npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill

Shell Completion

flywheel completion <shell> generates shell completion scripts from the public Flywheel command spec. It requires the official usage executable on PATH; install it with one of:

mise use -g usage
brew install usage
cargo install usage-cli
cargo binstall usage-cli
pacman -S usage

Install generated completions into user-level locations:

flywheel completion install bash
flywheel completion install zsh --update-profile --yes
flywheel completion install fish
flywheel completion install powershell --update-profile --yes
flywheel completion install nu
flywheel completion install nushell

Remove Flywheel-managed completion files and profile blocks with the matching uninstall command:

flywheel completion uninstall bash
flywheel completion uninstall zsh --update-profile --yes
flywheel completion uninstall fish
flywheel completion uninstall powershell --update-profile --yes
flywheel completion uninstall nu

Profile/startup file edits are opt-in. Without --update-profile, installation writes only the generated completion file. Use --dry-run to inspect planned changes, --dir <path> to choose a destination directory, and --force only when replacing an existing unmarked completion file.

You can also generate the script for your shell and redirect it yourself:

flywheel completion bash --include-bash-completion-lib > ~/.local/share/bash-completion/completions/flywheel
flywheel completion zsh > ~/.zsh/completions/_flywheel
flywheel completion fish > ~/.config/fish/completions/flywheel.fish
flywheel completion powershell > flywheel.ps1
flywheel completion nu > ~/.config/nushell/autoload/flywheel.nu
flywheel completion nushell > ~/.config/nushell/autoload/flywheel.nu

flywheel completion <shell> generates scripts only. It does not install completions, touch shell startup files, or edit shell profiles. flywheel setup also does not install completions; completion installation remains an explicit flywheel completion install <shell> action.

Uninstall

One-shot uninstaller (macOS and Linux):

curl -fsSL https://flywheel.paradigma.inc/uninstall | sh

The script removes Flywheel MCP entries, bundled skills, the managed-prefix @paradigma-inc/flywheel package, the flywheel binary, installer-owned PATH block, default CLI config/profiles under ~/.config/flywheel-cli, and the local runtime cache under ~/.flywheel. It does not delete remote Flywheel account data, nodes, artifacts, billing data, GitHub connections, or other remote resources.

Manual fallback:

FLYWHEEL_INSTALL_PREFIX="${FLYWHEEL_INSTALL_PREFIX:-$HOME/.local}"
"$FLYWHEEL_INSTALL_PREFIX/bin/flywheel" uninstall --yes --scope all
npm uninstall -g --prefix "$FLYWHEEL_INSTALL_PREFIX" @paradigma-inc/flywheel
rm -rf "$HOME/.config/flywheel-cli" "$HOME/.flywheel"

With --yes --scope all and no host selectors, flywheel uninstall targets every supported host.

Setup Modes

# canonical
npx --yes @paradigma-inc/flywheel setup --mode <mcp|cli>

# aliases
npx --yes @paradigma-inc/flywheel setup --mcp
npx --yes @paradigma-inc/flywheel setup --cli

Mode behavior:

• --mode mcp / --mcp: MCP config setup path (plus optional bundled skill install path).
• --mode cli / --cli: bundled skill install path only, no MCP config writes, no shell mutation.

If mode is omitted:

• interactive TTY: prompt for mcp or cli (default mcp)
• non-interactive: fails with usage error (exit 2)

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.

Non-Interactive Flows

MCP setup (without bundled skill installation):

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

MCP setup (with bundled skill installation):

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

CLI-only bundled skill setup:

npx --yes @paradigma-inc/flywheel setup --mode cli

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

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 \
  --mode mcp \
  --auth-mode device \
  --skip-skill \
  --base-url https://flywheel.paradigma.inc

Runtime Config Bootstrap

setup --mode mcp now also provisions the runtime CLI config so that post-setup runtime commands (flywheel auth:status, flywheel nodes:list, etc.) work immediately without manual steps.

On successful authentication, the setup writes a JSON config at:

• FLYWHEEL_CLI_CONFIG_PATH (when set)
• $HOME/.config/flywheel-cli/config.json (default)

The resolved runtime base URL always includes the /api suffix (for example https://flywheel.paradigma.inc/api), matching the runtime API mount point. The runtime command surface is documented in project/flywheel-cli/README.md.

Argument Syntax (Runtime Commands)

Runtime commands (auth:*, nodes:*, artifacts:*, compute:*, export:*) use GNU-style long flags: --key value, --key=value, or --boolean_flag. JSON payload commands accept [email protected] to load payloads from disk. See project/flywheel-cli/README.md for full details.

Scope Rules

• Default scope (no --project) is user-level/global.
• --project is the explicit repo-local override.

Examples:

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

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

Host Matrix

| Host | MCP wiring (--mode mcp) | CLI-mode bundled skill install (--mode cli) | | ----------------------------- | ------------------------- | --------------------------------------------- | | Claude Code | yes | yes | | Cursor | yes | yes | | Universal (.agents/skills) | no (skill-only) | yes | | Antigravity (.agent/skills) | no (skill-only) | yes | | OpenCode | yes | yes | | Codex | yes | yes | | Gemini CLI | yes | yes | | Pi (pi-mono) | yes | yes | | OpenClaw | yes | yes | | Hermes Agent | yes | no (MCP-only host) |

CLI mode handling for Hermes Agent:

• unsupported-only selection: command fails with usage error (exit 2)
• mixed supported + unsupported selection: command continues for supported hosts and reports skipped unsupported hosts

New flags (ctx7 alignment)

These flags align the flywheel setup surface with the npx ctx7 setup convention while keeping every Flywheel-specific flag intact. They are additive: existing invocations continue to behave as before.

--oauth

Writes an MCP config that omits the Authorization header and delegates authentication to the IDE's MCP 2.0 OAuth discovery flow. No API key is minted, stored, or transmitted by flywheel setup itself.

npx --yes @paradigma-inc/flywheel setup --mode mcp --claude --oauth --project

The resulting .mcp.json:

{
  "mcpServers": {
    "flywheel": {
      "type": "http",
      "url": "https://flywheel.paradigma.inc/mcp-server"
    }
  }
}

The IDE must support MCP 2.0 OAuth discovery (Claude Code, Cursor, and Gemini CLI currently do). On the first MCP tool call the IDE hits /mcp-server, follows the WWW-Authenticate hint to /.well-known/oauth-protected-resource, registers itself via /oauth/register, completes the browser flow, and from then on manages its own refresh tokens. No API key ever touches the user's filesystem.

--api-key and --oauth are mutually exclusive; passing both produces a usage error (exit 2).

If a previous flywheel setup run wrote an MCP entry with an Authorization header against the same URL, re-running with --oauth will classify that entry as matching and leave the header in place. To rewrite the config to drop the header, first run flywheel uninstall --<host> --project and then re-run setup with --oauth.

--gemini

Registers Flywheel as an MCP server for Gemini CLI at .gemini/settings.json (project) or ~/.gemini/settings.json (global). Gemini CLI uses the mcpServers.flywheel.httpUrl key (not url); when --api-key <key> is supplied, the setup writes a Bearer <key> Authorization header. With --oauth the header is omitted.

npx --yes @paradigma-inc/flywheel setup --mode mcp --gemini --project --api-key <token>

--universal

Skill-only target that writes Flywheel's bundled skills into ./.agents/skills/<skill-name>/ (project) or ~/.agents/skills/<skill-name>/ (global). Writes no MCP server config and no agent-specific rules. Useful for toolchains that read the conventional .agents/skills/ layout without needing a Flywheel MCP binding. Requires --mode cli explicitly and is never auto-detected; opt-in only.

npx --yes @paradigma-inc/flywheel setup --mode cli --universal --project

--antigravity

Same skill-only shape as --universal but targets ./.agent/skills/<skill-name>/ (project) or ~/.agent/skills/<skill-name>/ (global) — note the singular .agent directory. Writes no MCP server config. Requires --mode cli explicitly and is never auto-detected.

npx --yes @paradigma-inc/flywheel setup --mode cli --antigravity --project

Public Update Flow

Flywheel checks for newer public CLI releases during normal command use and prints stale-version advisories to stderr only. To update the managed local package and refresh detected local MCP host and bundled-skill setup artifacts, run:

flywheel update --yes

Check status without changing files:

flywheel update --check

Preview package and local setup refresh steps without changing files:

flywheel update --dry-run

If no local Flywheel setup artifacts are detected, rerun the public installer:

curl -fsSL https://flywheel.paradigma.inc/install | sh

Troubleshooting

Advanced troubleshooting (optional): inspect installed skill state directly.

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

If bundled skills are missing, rerun setup with explicit mode and desired skill flags.

Other Commands

• setup: setup flow with explicit mode routing.
• uninstall: removes Flywheel MCP entries from host configs and removes bundled skills from supported hosts. Use the one-shot uninstaller above for a full local cleanup, including the global npm package and default local state.

npx --yes @paradigma-inc/flywheel uninstall

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