CLI Command Reference

The optimal CLI organizes its commands into logical groups that map to the core workflows of the Optimal platform. Each group handles a distinct domain — from kanban task management to financial pipelines, content generation, and infrastructure operations.

Installation

pnpm install -g optimal-cli

After installing, run the setup wizard:

optimal sync config init --owner your-org --brand CRE-11TRUST
optimal doctor

Command Groups

Group	Description
board	Kanban board: create, update, claim, and track tasks (epic/story/task hierarchy). Includes auto-claim and tui.
finance	ReturnPro financial pipeline: uploads, audits, KPIs, monthly close, R1 volume.
content	Newsletter, social, blog, scraping, research pipeline, intelligence reports.
agent	Bot orchestration: heartbeats, task claiming, coordination.
tx	Bank transaction ingestion, categorization, and cleanup.
infra	Deployments, health checks, Supabase migrations, instance monitoring.
sync	Discord sync, config profile management, bot registration.
scenario	Budget scenario CRUD (save, list, compare, delete).
Auth & Doctor	optimal login, signup, logout, session list, doctor.
config	Shared environment variable sync (config seed-shared, config pull-shared).
asset	Digital infrastructure asset tracking (domains, servers, API keys, repos).
project	Project management (list, create, update).
milestone	Milestone tracking (create, list).
label	Label management (create, list).

Additional Commands

Beyond the main groups above, the CLI includes several standalone commands.

Project Management

optimal project list                                     # List all projects
optimal project create --slug my-proj --name "My Proj"   # Create a project
optimal project update --slug my-proj -s active          # Update a project

Milestones

optimal milestone list --project <slug>                              # List milestones
optimal milestone create --project <slug> --name "v1.0" --due 2026-04-01  # Create a milestone

Labels

optimal label list                              # List all labels
optimal label create --name "bug" --color "#FF0000"   # Create a label

Assets

optimal asset list                 # List tracked assets
optimal asset add --name "API Key" --type api_key   # Add a new asset
optimal asset update --id <uuid> --status expired    # Update an asset
optimal asset get --id <uuid>                        # Get asset details
optimal asset remove --id <uuid>                     # Delete an asset
optimal asset track --id <uuid> --event "rotated"    # Log a usage event
optimal asset usage --id <uuid>                      # View usage log

Scenarios

See Scenarios for full reference.

optimal scenario list
optimal scenario save --name "base" --adjustment-type percentage --adjustment-value 4
optimal scenario compare --names "base,aggressive"
optimal scenario delete --name "old-scenario"

Authentication & Diagnostics

See Auth & Doctor for full reference.

optimal login                      # Authenticate with Supabase
optimal signup                     # Create a new account
optimal logout                     # Clear stored credentials
optimal session list               # List active terminal sessions
optimal doctor                     # Full system health check (--fix to repair)

Global Flags

These flags are available on every command:

Flag	Description
--help	Show help for any command
--version	Show CLI version
--json	Output as JSON (where supported, e.g. board, asset, research commands)

Environment Variables

The CLI reads from a .env file in the project root or from your shell environment.

Variable	Required	Purpose
OPTIMAL_SUPABASE_URL	Yes	OptimalOS Supabase instance URL
OPTIMAL_SUPABASE_SERVICE_KEY	Yes	OptimalOS service role key
RETURNPRO_SUPABASE_URL	For finance	ReturnPro Supabase instance URL
RETURNPRO_SUPABASE_SERVICE_KEY	For finance	ReturnPro service role key
GROQ_API_KEY	For content	Used by AI content generation (Groq/Llama)
STRAPI_URL	For content	Strapi CMS URL
STRAPI_API_TOKEN	For content	Strapi API token
DISCORD_BOT_TOKEN	For sync	Discord bot token for sync commands
N8N_WEBHOOK_URL	For pipelines	n8n webhook URL for distribution and pipelines
META_ACCESS_TOKEN	For Instagram	Meta Graph API access token