Foundation Operator CLI (fops)

Install and manage Foundation data mesh platforms from the terminal.

Install

npm / npx (recommended)

# Run without installing
npx @meshxdata/fops doctor

# Install globally
npm install -g @meshxdata/fops

From repo (development)

cd foundation-compose/operator-cli
npm install
npm link   # optional: use `fops` from anywhere

Commands

| Command | Description | |---------|-------------| | fops login | Authenticate with Claude (default) or other services | | fops login coda | Authenticate with Coda (guided API token setup) | | fops setup | Full automated setup (.env, netrc reminder, submodules; use --download to pull images) | | fops init | Initialize a Foundation project. Interactive wizard when not in a project root. | | fops up | Start all services (make start); launches interactive AI assistant after startup | | fops down | Stop services; use --clean to remove volumes | | fops status | Show service status | | fops logs [service] | Stream logs (all or one service) | | fops doctor | Check Docker, git, .env, AWS/ECR, ports, services; use --fix to apply fixes | | fops config | Launch interactive configuration | | fops bootstrap | Create demo data mesh | | fops test | Run health checks | | fops agent | AI assistant for the stack. Interactive or single-turn with -m "message". | | fops chat | Interactive AI assistant (same as fops agent) | | fops skill list | List available agent skills (built-in and plugin-provided) | | fops plugin list | List installed plugins | | fops plugin install <source> | Install a plugin from a local directory | | fops plugin remove <id> | Remove an installed plugin |

AI Assistant (agent / chat)

• Interactive: fops agent or fops chat — in-CLI chat with streaming responses and command execution.
• Single-turn: fops agent -m "why are my containers failing?" — one question, one reply; optional "run suggested command?" prompt.
• Model override: fops agent --model claude-sonnet-4-20250514

Auth (checked in order):

1. Claude Code CLI OAuth (if claude is installed and authenticated)
2. ANTHROPIC_API_KEY environment variable
3. ~/.claude/settings.json → apiKeyHelper (script that prints the API key)
4. ~/.claude/.credentials.json or ~/.claude.json → anthropic_api_key / apiKey
5. OPENAI_API_KEY environment variable (fallback; uses OpenAI-compatible models)

Run fops login to authenticate via OAuth browser flow, or fops login --no-browser to paste an API key directly.

Example: Configuring API key in ~/.claude.json

{
  "anthropic_api_key": "sk-ant-api03-..."
}

Or in ~/.claude/.credentials.json:

{
  "ANTHROPIC_API_KEY": "sk-ant-api03-...",
  "OPENAI_API_KEY": "sk-proj-..."
}

Coda — Run fops login coda to set up your Coda API token. The wizard opens your browser to coda.io/account and guides you through generating and pasting the token. Token is validated via the Coda API and saved to ~/.fops.json. You can also set CODA_API_TOKEN as an env var.

Doctor

Checks prerequisites (Docker, Git, Node.js, AWS CLI), AWS/ECR access, project structure, Docker resources, port conflicts, running services, and image freshness. Plugins can register additional checks.

On --fix, doctor can automatically:

• Install Docker (macOS via Homebrew, Windows via winget, Linux via get.docker.com)
• Start the Docker daemon
• Fix AWS SSO sessions and ECR authentication
• Create missing .env from .env.example
• Run fops init for missing projects
• Rebuild stale images

Plugins

Plugins extend the CLI with custom commands, doctor checks, lifecycle hooks, and agent skills.

• Global plugins: ~/.fops/plugins/<id>/ (each with fops.plugin.json)
• NPM plugins: packages named fops-plugin-* or @scope/fops-plugin-*

Usage

Run from a foundation-compose clone (or any directory containing docker-compose.yaml and Makefile). You can also set FOUNDATION_ROOT to point to your repo root.

cd /path/to/foundation-compose
fops doctor
fops up
fops status

First-time setup:

fops init
fops up

The init wizard will prompt to clone the repository if no project is found.

Requirements

• Node.js >= 18
• Docker (Docker Compose)
• Git (for submodules)
• Claude CLI (bundled — installed automatically via npm install)

License

MIT