CLI Command Reference

The optimal CLI organizes its commands into logical groups that map to the core workflows of the Optimal platform.

Command Groups

Group	Description
board	Manage tasks on the Kanban board backed by Supabase.
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.
transactions	Bank transaction ingestion, categorization, and cleanup.
infra	Deployments, health checks, Supabase migrations, instance monitoring.
sync	Discord sync, config profile management, bot registration.
scenarios	Budget scenario CRUD (save, list, compare, delete).
auth	Authentication and system diagnostics.

Installation

pnpm install -g optimal-cli

After installing, run the setup wizard:

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

Global Flags

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

Environment Variables

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	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

Additional Commands

optimal project

Project management

optimal project list

List all projects

optimal project create

Create a project

Flag	Description	Default	Required
--slug <slug>	Project slug		yes
--name <name>	Project name		yes
--owner <name>	Owner
--priority <n>	Priority 1-4	3

optimal project update

Update a project

Flag	Description	Default	Required
--slug <slug>	Project slug		yes
-s, --status <status>	New status
--owner <name>	New owner

optimal milestone

Milestone management

optimal milestone create

Create a milestone

Flag	Description	Default	Required
--project <slug>	Project slug		yes
--name <name>	Milestone name		yes
--due <date>	Due date (YYYY-MM-DD)

optimal milestone list

List milestones

Flag	Description	Default	Required
--project <slug>	Filter by project

optimal label

Label management

optimal label create

Create a label

Flag	Description	Default	Required
--name <name>	Label name		yes
--color <hex>	Color hex code

optimal label list

List all labels

optimal asset

Digital asset tracking (domains, servers, API keys, services, repos)

optimal asset list

List tracked assets

Flag	Description	Default	Required
-t, --type <type>	Filter by type
-s, --status <status>	Filter by status
-o, --owner <owner>	Filter by owner
--json	Output as JSON

optimal asset add

Add a new asset

Flag	Description	Default	Required
-n, --name <name>	Asset name		yes
-t, --type <type>	Asset type		yes
-s, --status <status>	Status (default: active)
-o, --owner <owner>	Owner
--expires <date>	Expiration date
--meta <json>	Metadata JSON string

optimal asset update

Update an existing asset

Flag	Description	Default	Required
--id <uuid>	Asset ID		yes
-n, --name <name>	New name
-t, --type <type>	New type
-s, --status <status>	New status
-o, --owner <owner>	New owner
--expires <date>	New expiration date
--meta <json>	New metadata JSON

optimal asset get

Get a single asset by ID

Flag	Description	Default	Required
--id <uuid>	Asset ID		yes

optimal asset remove

Delete an asset

Flag	Description	Default	Required
--id <uuid>	Asset ID		yes

optimal asset track

Log a usage event for an asset

Flag	Description	Default	Required
--id <uuid>	Asset ID		yes
-e, --event <event>	Event name		yes
--actor <name>	Who performed the action
--meta <json>	Event metadata JSON

optimal asset usage

View usage log for an asset

Flag	Description	Default	Required
--id <uuid>	Asset ID		yes
--limit <n>	Max entries	20

optimal config

Configuration management: shared env sync

optimal config seed-shared

Push local .env vars to shared_env_vars table (service_role)

Flag	Description	Default	Required
--env-file <path>	Path to .env file	.env

optimal config pull-shared

Pull shared env vars and merge into local .env

Flag	Description	Default	Required
--email <email>	Owner email to pull from (defaults to OPTIMAL_OWNER_EMAIL or cached auth)
--env-file <path>	Path to .env file to write	.env