ionctl

Interactive CLI for local development of the Ionize Identity Platform.

What It Does

ionctl deploy — Bootstrap Local Stack

Auto-installs Podman, podman-compose, and kubectl via Homebrew (macOS), initializes and starts the Podman machine, builds dev container images, starts all services in the correct order (infrastructure → migrations → Ory → apps → seed), verifies health and displays access URLs + test credentials.

ionctl destroy — Stop & Clean

Stop and remove all dev containers, volumes, and images.

ionctl — Interactive Menu

Running without arguments shows a menu with Deploy / Destroy options.

Production deployment is handled by Daedalus — the deployment wizard. Version bumps are handled by the Release Manager agent.

Prerequisites

• Node.js 20+ and npm (runtime)

The following are auto-installed by ionctl deploy if missing:

• Podman, podman-compose, and kubectl (via Homebrew on macOS, apt on Linux)

Installation

npm install -g @nannier/ionctl

Then run from anywhere:

ionctl dev

(Bare ionctl opens an interactive menu with the same actions.)

Workspace

ionctl is part of the Ionize Identity Platform. All repos should be cloned as siblings under a shared workspace:

Ionize/
├── platform/    # Infrastructure & Podman Compose
├── dashboard/      # Admin dashboard
├── auth/        # Auth & consent UI
├── services/    # Backend API tier (ciam-core :3002, iam-core :4002)
├── site/        # Brochure site & OAuth2 playground
├── canvas/      # Design system
├── sdk/         # Shared settings & encryption
└── ionctl/        # CLI tool (this repo)

Dev Service Ports

| Service | Port | |---------|------| | Site | 2000 | | CIAM Auth (login) | 3000 | | CIAM Dashboard (admin) | 3001 | | CIAM Services (api) | 3002 | | IAM Auth (login) | 4000 | | IAM Dashboard (admin) | 4001 | | IAM Services (api) | 4002 | | pgAdmin | 5433 | | Mailslurper | 5434 |

The services tier (ciam-core / iam-core, from the bnannier/core repo) hosts all backend logic for Dashboard and Auth, and is the only application tier that talks to the shared ionize database. The 3002/4002 host bindings are a dev-only debugging convenience — production exposes no host ports for it.

Tech Stack

| Category | Technology | |----------|-----------| | Runtime | Bun (ESM) | | Language | TypeScript | | Prompts | @inquirer/prompts | | Linting | Biome |

Project Structure

src/
├── index.ts               # Main CLI entry — menu dispatch
├── types.ts               # DevAction type
├── commands/
│   └── dev.ts             # Local dev: install Podman, build, start, seed, destroy
└── lib/
    ├── shell.ts           # Command execution (exec, execInteractive)
    └── ui.ts              # Terminal formatting + colors

License

MIT