Flow Mesh CLI Specification
Status: Definitive spec. Implementation MUST match this document. Audience: Developers, AI agents, CI/CD pipelines.
Design Principles
- Agent-first. Every operation available in the UI is available via CLI with
--format jsonoutput. Zero context cost for AI agents — no MCP needed for basic workflows. - Single binary.
mesh <command> [subcommand] [flags]. No daemon required for read operations (reads DB directly).servestarts the HTTP server + sync engine. - Predictable flags. Global flags parsed before dispatch. Per-command flags after the subcommand.
--configalways works.--format jsonalways works. - Safe defaults. Destructive operations require explicit IDs. No silent data loss. FK constraints validated before INSERT.
- Composable. Every command that produces output supports
--format jsonfor piping. Commands accept IDs from stdin where it makes sense.
Global Flags
Parsed in main() before command dispatch. Available to ALL commands:
| Flag | Type | Default | Description |
|---|---|---|---|
--config |
string | config.yaml |
Path to config file |
--format |
string | text |
Output format: text or json |
When --format json is set, all output is machine-parseable JSON. Errors go to stderr. Human-readable tables go to stdout only in text mode.
File Structure
Split cmd/mesh/main.go (currently 1500+ LOC) into:
cmd/mesh/
main.go — main(), dispatch, global flag parsing, loadCfg, openDB helpers
serve.go — cmdServe
ps.go — cmdPS: create, list, show, delete, activate, pause, link, unlink, import
task.go — cmdTask: create, list, show, update, close, delete, comment
events.go — cmdEvents
config.go — cmdConfig: show, init, validate
setup.go — cmdSetup: nginx, caddy, cloudflared
automesh.go — cmdAutoMesh: status, enable, disable, add-folder, remove-folder, list-folders, templates, poll
intel.go — cmdAsk, cmdChat, cmdMCP
sync.go — cmdSync, cmdDrift
export.go — cmdExport: events, snapshot
providers.go — cmdProviders
Each file is package main. Shared helpers (loadCfg, openDB, logCLIEvent, writeJSONOut, parseFlags) stay in main.go.
Commands
mesh serve
Start the HTTP server, sync engine, and auto-mesh poller.
mesh serve [--config path] [--port PORT]
| Flag | Description |
|---|---|
--port |
Override listen port (0 = random, for Tauri sidecar) |
Prints LISTEN_ADDR=host:port to stdout for machine consumption.
mesh status
Show service and connection status. Reads DB + tests Asana/Discord connectivity.
mesh status [--config path] [--format json]
JSON output:
{
"version": "0.2.0",
"db_path": "./data/flow-mesh.db",
"db_version": 10,
"listen_addr": "127.0.0.1:8300",
"asana": true,
"discord": true,
"project_spaces": 4,
"work_items": 12,
"pending_events": 0
}
mesh ps — Mesh Lifecycle
Full CRUD for meshes (project spaces). This is the primary agent workflow command.
mesh ps list
mesh ps list [--state STATE] [--format json]
| Flag | Description |
|---|---|
--state |
Filter: detected, configured, active, paused, ignored, error |
JSON output:
{
"meshes": [
{
"id": "019c72ea-...",
"name": "My Project",
"state": "active",
"origin": "mesh",
"created": "2026-02-19T22:41:22Z",
"updated": "2026-02-19T22:41:22Z"
}
],
"count": 1
}
mesh ps show <id>
mesh ps show <mesh-id> [--format json]
Returns full mesh detail including all linked representations, policy, and stats.
JSON output:
{
"id": "019c72ea-...",
"name": "My Project",
"state": "active",
"origin": "mesh",
"created": "...",
"updated": "...",
"server": {
"repo_path": "/data/my-project",
"repo_id": "abc123",
"beads_enabled": true
},
"asana": {
"project_gid": "123456789",
"workspace_gid": "987654321"
},
"discord": {
"forum_channel_id": "111222333",
"guild_id": "444555666",
"mode": "full"
},
"policy": {
"sync_mode": "bidirectional",
"comment_mode": "full_projection",
"approval_mode": "none",
"representation_asana": "linked",
"representation_server": "linked",
"representation_discord": "managed"
},
"stats": {
"work_items": 5,
"pending_events": 0
}
}
mesh ps create
Create a new mesh with optional representations linked in one shot.
mesh ps create "Project Name" \
[--repo /path/to/repo] \
[--asana PROJECT_GID] \
[--discord CHANNEL_ID] \
[--discord-create] \
[--asana-create] \
[--template A|B|C] \
[--activate] \
[--format json]
| Flag | Description |
|---|---|
--repo PATH |
Link an existing git repo (must have .git/) |
--asana GID |
Link an existing Asana project by GID |
--asana-create |
Create a new Asana project (uses mesh name) |
--discord ID |
Link an existing Discord forum channel |
--discord-create |
Create a new Discord forum channel (uses mesh name) |
--template |
Policy template: A (default, read-only), B (bidirectional), C (mirror) |
--activate |
Immediately transition to active state (default: configured) |
Behavior:
- Generates UUIDv7 for
project_space_id. - Inserts into
project_spaceswith stateconfigured. - If
--repo: validates path exists, has.git/, inserts intoproject_space_server. Detects beads. - If
--asana GID: inserts intoproject_space_asana. - If
--asana-create: calls Asana API to create project + custom fields, inserts mapping. - If
--discord ID: inserts intoproject_space_discordwith modefull. - If
--discord-create: calls Discord API to create forum channel, pins metadata, inserts mapping. - Inserts
project_space_policybased on template, with representation flags matching what was linked. - If
--activate: transitions state toactive. - Logs
createevent toevent_ledger.
JSON output:
{
"mesh_id": "019c...",
"name": "Project Name",
"state": "configured",
"template": "B",
"server": {"repo_path": "/data/project", "linked": true},
"asana": {"project_gid": "123", "linked": true},
"discord": {"channel_id": "456", "created": true}
}
Errors:
- Repo path doesn't exist or has no
.git/→ exit 1, stderr message. - Asana/Discord API fails → mesh still created with partial representations, warning on stderr.
- Name is empty → exit 1.
mesh ps delete <id>
Delete a mesh and ALL related data. Cascades through all tables.
mesh ps delete <mesh-id> [--format json]
Behavior:
- Validates mesh exists.
- Rejects
_global(cannot delete). - Deletes from:
project_space_policy,project_space_server,project_space_asana,project_space_discord,work_items,approvals,event_ledger,project_spaces. - Does NOT delete actual git repos, Asana projects, or Discord channels — only the mesh's DB records.
JSON output:
{"deleted": "019c...", "name": "Project Name"}
mesh ps activate <id>
Transition mesh to active state. Sync engine will begin ingesting and projecting events.
mesh ps activate <mesh-id> [--format json]
Uses mesh.CanTransition() to validate. Fails if current state doesn't allow → active.
mesh ps pause <id>
Transition mesh to paused state. Events still ingested but not projected.
mesh ps pause <mesh-id> [--format json]
mesh ps link <id>
Add a representation to an existing mesh.
mesh ps link <mesh-id> \
[--repo /path] \
[--asana GID] \
[--asana-create] \
[--discord ID] \
[--discord-create] \
[--format json]
At least one of --repo, --asana, --discord, --asana-create, --discord-create required.
Behavior:
- Inserts/replaces into the appropriate mapping table.
- Updates
project_space_policyrepresentation flags. - Logs
representation_linkevent. - If
--asana-create: creates Asana project via API, adds custom fields. - If
--discord-create: creates Discord forum channel, pins metadata message.
mesh ps unlink <id>
Remove a representation from a mesh.
mesh ps unlink <mesh-id> --repo|--asana|--discord [--format json]
Exactly one of --repo, --asana, --discord required.
Behavior:
- Deletes from the mapping table (
project_space_server,project_space_asana, orproject_space_discord). - Updates
project_space_policyrepresentation flag tooff. - Logs
representation_unlinkevent. - Does NOT delete the actual repo/project/channel.
mesh ps import <id>
Run bootstrap import for a mesh.
mesh ps import <mesh-id> [--mode full|incremental] [--format json]
| Flag | Default | Description |
|---|---|---|
--mode |
full |
full = import all items; incremental = only new since last import |
Behavior:
- Reads Asana tasks and/or beads from linked representations.
- Creates
work_itemsin the DB. - Logs
importevent with count.
mesh task — Work Item CRUD
mesh task create
mesh task create "Title" \
[--title "Title"] \
[--mesh MESH_ID] \
[--status STATUS] \
[--priority P0-P4] \
[--note "Description"] \
[--format json]
| Flag | Default | Description |
|---|---|---|
--title |
(positional) | Task title. Positional arg also accepted. --title wins if both given. |
--mesh |
_global |
Mesh to create task in. Validated against project_spaces. |
--status |
backlog |
One of: backlog, ready, in_progress, blocked, review, done, archived |
--priority |
unset |
One of: P0, P1, P2, P3, P4, unset |
--note |
"" |
Task description/notes |
Behavior:
- Validates
--meshexists inproject_spaces(prevents FK crash). - Validates
--statusand--priorityagainst CHECK constraints. - Inserts into
work_items. - Logs
work_item_createevent.
JSON output:
{"work_item_id": "019c...", "mesh_id": "_global", "title": "Fix bug", "status": "backlog", "priority": "P1"}
mesh task list
mesh task list [--mesh ID] [--status STATUS] [--limit N] [--format json]
mesh task update <id>
mesh task update <work-item-id> [--status S] [--priority P] [--title T] [--note N] [--format json]
mesh task close <id>
mesh task close <work-item-id> [--format json]
Sets status to done. Projector cascades to Asana (completed:true), Discord (✅ prefix + message), Beads (bd close).
mesh task show <id>
mesh task show <work-item-id> [--format json]
Displays full work item detail including all linked representations.
Text output: Key-value pairs (ID, title, status, priority, assignee, due date, Asana GID, Beads ID, Discord thread ID).
JSON output:
{
"work_item_id": "019c...",
"title": "Implement auth",
"status": "in_progress",
"priority": "P1",
"assignee_asana_user_gid": "12345",
"due_date": "2026-03-15",
"asana_task_gid": "67890",
"beads_task_id": "abc-123",
"discord_thread_id": "111222333"
}
mesh task delete <id>
mesh task delete <work-item-id> [--force] [--format json]
Soft-deletes a work item (sets status to archived). Projector cascades:
- Asana:
DELETE /tasks/{gid} - Discord: Archive thread + "🗑️ Deleted" message
- Beads:
bd delete <id> --force
| Flag | Description |
|---|---|
--force |
Skip confirmation prompt |
mesh task comment <id> --text <text>
mesh task comment <work-item-id> --text "Comment text" [--format json]
| Flag | Description |
|---|---|
--text |
Comment text (required) |
Adds a comment to a work item. Creates an event in the ledger with type comment. Projector sends to all linked surfaces (Asana story, Discord thread message, Beads comment).
mesh project — project reads over the API
mesh project list # admitted projects, with origin and state
mesh project show <project_id> # one project
mesh project summary <project_id> # open work items and open cards
Reads the API rather than the database. A CLI that opens the database directly can disagree with the endpoint it is supposed to exercise, which is how a broken route stays invisible to the person most likely to notice.
The list excludes the _global ledger bucket: it exists so system events have a project to hang from, and it is not a project anyone admitted.
Watching a project
curl -N -H "Last-Event-ID: $CURSOR" "$FLOW_MESH_BASE_URL/api/v1/projects/<project_id>/activity-stream"
curl -N "$FLOW_MESH_BASE_URL/api/v1/projects/<project_id>/progress-stream"
Both streams are resumable, and both say so in the frame rather than leaving the client to guess:
- every frame carries an
id:; echo it back asLast-Event-ID(or as?cursor=) and the stream resumes after that position, so a reconnect neither loses nor repeats what the client already has; activity.streamresumes on(occurred_at, event_id)andprogress-streamon(updated_at, card_id). The card id is a required tiebreaker: timestamps are second-resolution, so two cards touched in the same second would otherwise be indistinguishable and one of them would be skipped invisibly rather than late;- when a cursor cannot be placed in history — an event aged out, a ledger replaced — the stream sends
event: resyncwithreason: cursor_not_foundand the newest window. The spec requires a client to fetch a snapshot when replay is unavailable; a silent jump would look like "nothing was missed", which is the one answer that cannot be recovered from; - a quiet stream still emits
: keep-alivecomments, so an idle proxy does not close a connection that is working correctly.
?interval_ms= sets the poll cadence (50–30000, default 500); anything outside that range is refused rather than clamped, because a client asking for 1ms is asking for something the server will not do. mesh project watch / mesh progress watch are declared bindings and not yet wired in cmd/mesh; use curl -N until they are.
Inbound webhooks
There is no CLI command for receiving a delivery; the endpoint is the surface:
curl -X POST "$FLOW_MESH_BASE_URL/api/v1/integrations/asana/webhooks/<project_id>/<binding_id>" \
-H "X-Hook-Signature: $(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$FLOW_MESH_WEBHOOK_SECRET_ASANA" -r | cut -d' ' -f1)" \
-H "X-Delivery-Id: ..." --data-binary "$BODY"
Set FLOW_MESH_WEBHOOK_SECRET_<ADAPTER> (upper-cased, dashes to underscores) to verify a provider's deliveries. Without it the endpoint refuses rather than trusting the sender.
mesh batch read — several reads in one request
mesh batch read requests.json
The file is the endpoint's own request body ({"items":[{"operation_id":..., "path_params":{...},"query":{...}}]}), so there is one description of a batch rather than a CLI dialect of it. Up to twenty reads; mutations and streams are refused. A partial failure exits non-zero and lists which items failed.
mesh work show / mesh work links — read one work item
mesh work show <work-item-id>
mesh work links <work-item-id>
Both read the running service rather than opening the database, so the CLI cannot disagree with the endpoint it is meant to exercise. Mutations still go through mesh work complete|delegate|update|comment, which require an authority reference.
mesh adapter validate / mesh adapter health — check an adapter
mesh adapter validate <adapter_id> --file manifest.json
mesh adapter health <adapter_id>
validate returns the findings that explain a failure rather than a bare boolean. health reports registration and whether the credential variable the adapter names is set; it never returns the value. The HTTP surface is served (POST /api/v1/adapters/{id}/validate|health); the subcommands above are not yet wired in cmd/mesh, so use curl until they are.
mesh integration — what this project actually linked
mesh integration list <project_id>
mesh integration health <project_id> <adapter_id>
mesh integration bind <project_id> <adapter_id> --kind project --ref <external_ref> \
--name "..." --idempotency-key <key>
mesh integration unbind <project_id> <adapter_id> <binding_id> [--reason "..."]
mesh integration revoke <project_id> <adapter_id> [--reason "..."]
mesh integration discover <project_id> <adapter_id>
mesh integration reconcile <project_id> <adapter_id> --idempotency-key KEY
unbind revokes one binding and keeps the row; revoke covers every active binding for an adapter and prints the count it changed. list flags any binding whose adapter is no longer registered — an orphaned binding still reports active, which is exactly why the flag exists.
mesh instruction — directives, and the authority they need
mesh instruction list <project_id>
mesh instruction add <project_id> --class directive --source discord --ref <ref> \
--body "..." --idempotency-key <key>
mesh instruction acknowledge <project_id> <instruction_id> \
--authority <authority_ref> --receipt <receipt_ref>
mesh instruction reject <project_id> <instruction_id> --reason "..."
A new instruction is always pending. acknowledge fails with POLICY_DENIED unless both an authority reference and a receipt are given — text does not mint permission. reject requires a reason, because a rejection without one is indistinguishable from having forgotten the instruction.
mesh evidence — record and read proof
mesh evidence add <project_id> --kind test --ref <handle> --target <what it proves> \
--summary "what it shows" --idempotency-key <key>
mesh evidence list <project_id>
mesh evidence show <project_id> <evidence_id>
--idempotency-key is required: a retry must return the existing record rather than recording the same proof twice. Kinds are file, test, url, receipt and observation — the last is for proof that cannot be re-derived, which is still evidence but cannot be re-run.
mesh adapter — registered integration adapters
mesh adapter list # adapters this deployment registered
mesh adapter show <adapter> # full manifest: role, version, auth fields, env vars
Reads the live provider registry through the API. A manifest lists what an adapter needs to authenticate (field keys, environment variable names), never a value.
mesh activity — the project ledger
mesh activity list <project_id> [--limit N] [--format json]
Pages GET /api/v1/projects/{id}/activity in ledger order. Each row shows when it occurred, what happened, which system reported it, who acted, and how far it has been projected to other surfaces.
mesh capability — what the contract offers, and what is actually answered
mesh capability list [--format json]
Reads GET /api/v1/capabilities from the running service and prints every operation in the registry with its method, path, CLI binding, required capability, scope, and whether a handler answers it today. A capability marked declared is in the contract but has no handler; its reason is recorded in internal/operations/parity-gaps.v1.json.
Reports from the service rather than from a local copy deliberately: a contract command that still answers while the daemon is down is reporting a fiction.
mesh schema — the published contract document
mesh schema list # name and version of every published definition
mesh schema show <name> [version] # the full JSON Schema for one definition
show defaults to version v1. Both read from the service, which generates the document from the registry per request, so what you see is what the build ships.
Requires FLOW_MESH_BASE_URL (or a configured listen address) — see mesh providers for the same resolution.
mesh bootstrap
Scan server inventory and bootstrap intelligence + configuration.
mesh bootstrap [--domain DOMAIN] [--auto] [--dry-run] [--no-intelligence] [--format json]
| Flag | Description |
|---|---|
--domain |
Target domain (triggers CF tunnel setup suggestions) |
--auto |
Auto-configure everything possible without prompting |
--dry-run |
Show inventory without making changes |
--no-intelligence |
Skip LLM key probing |
Behavior:
- Scans env vars for LLM API keys (Anthropic, OpenAI, Kimi, OpenRouter, Ollama)
- Scans for tools (cloudflared, pi, bd, git, docker)
- Checks port 8300, OS, init system
- Tests LLM connectivity with ping
- If
--auto: stores LLM config, creates admin user - Prints next steps
mesh sync
Trigger a manual sync cycle for a mesh (or all active meshes).
mesh sync [MESH_ID] [--format json]
| Arg | Default | Description |
|---|---|---|
MESH_ID |
(all active) | Specific mesh to sync. Omit for all active meshes. |
Behavior:
- If mesh ID given: validates mesh exists and is
active. - Runs one cycle of: poll beads → ingest events → project pending events.
- Reports events ingested and projected.
JSON output:
{"mesh_id": "019c...", "events_ingested": 3, "events_projected": 2}
mesh drift
Run drift detection across representations.
mesh drift [MESH_ID] [--fix] [--format json]
| Flag | Description |
|---|---|
--fix |
Auto-repair safe drifts (title mismatches, status mismatches) |
Behavior:
- For each active mesh (or specified mesh): compare work items across linked representations.
- Report field-level drifts.
- If
--fix: apply safe repairs and log events.
JSON output:
{
"mesh_id": "019c...",
"drifts": [
{"work_item_id": "...", "field": "title", "asana": "Bug fix", "beads": "Bug Fix", "auto_fixable": true}
],
"fixed": 1,
"remaining": 0
}
mesh events
List event ledger entries.
mesh events [--ps ID] [--state STATE] [--type TYPE] [--since DURATION] [--limit N] [--watch] [--format json]
| Flag | Default | Description |
|---|---|---|
--ps |
(all) | Filter by mesh ID |
--state |
(all) | Filter: pending, projected, failed, partial, conflict |
--type |
(all) | Filter by event type (e.g., create, update, status_change) |
--since |
(all) | Duration filter: 1h, 24h, 7d |
--limit |
100 |
Max events to return |
--watch |
false | Tail mode: poll every 2s for new events |
mesh conflicts
Show cross-system conflicts.
mesh conflicts [--mesh ID] [--format json]
JSON output:
{
"conflicts": [
{
"work_item_id": "...",
"mesh_id": "...",
"field": "status",
"sources": {"asana": "done", "beads": "in_progress"},
"detected_at": "..."
}
],
"count": 1
}
mesh export
Export data for backup or analysis.
mesh export events
mesh export events [--ps ID] [--since DURATION] [--format json|csv]
mesh export snapshot
Full system snapshot: all meshes, work items, policies, events.
mesh export snapshot [--format json]
mesh providers
Report every declared integration and its live state.
mesh providers [--format json]
The report covers the whole catalog, not only the integrations that happen to be configured. That distinction matters: a list of connected things cannot tell an operator whether an integration is missing or merely absent from the report, and the command previously omitted the one provider that was actually live.
States:
| State | Meaning |
|---|---|
connected |
Configured and, where a live check exists, confirmed responding |
not_connected |
Configured but not currently connected |
not_configured |
The driver exists in this build; no configuration or credential path is wired at this deployment |
unknown |
Could not be determined — for example the service was unreachable |
unknown is deliberately distinct from not_configured. Reading an unreachable service as a missing integration is how a live provider gets declared absent.
Google Tasks is reported by asking the running service, because its state depends on encrypted credential storage, broker configuration and workload identity. Set FLOW_MESH_BASE_URL when the service is not on the default listen address:
FLOW_MESH_BASE_URL=http://127.0.0.1:8300 mesh providers
JSON output:
{
"count": 14,
"integrations": [
{"name": "asana", "role": "tracker", "driver": "asanaprov", "state": "connected", "detail": "workspace 1201470256117614"},
{"name": "google-tasks", "role": "tasks", "driver": "googletasks", "state": "connected", "authority": "direct_oauth", "detail": "renewable"},
{"name": "jira", "role": "tracker", "driver": "jiraprov", "state": "not_configured", "detail": "driver present, no configuration path wired for this deployment"}
]
}
Each entry also carries package, the repository path the driver is loaded from. A guard test compares the catalog against the provider packages on disk in both directions, so a newly added provider cannot stay invisible and a removed one cannot keep being reported.
mesh config
mesh config show — Print loaded config
mesh config show [--redact] [--format json]
| Flag | Default | Description |
|---|---|---|
--redact |
true |
Mask secrets (PATs, tokens). Use --redact=false to reveal. |
Default (redacted):
{
"db_path": "./data/flow-mesh.db",
"listen_addr": "127.0.0.1:8300",
"asana_pat": "1/12345...***",
"discord_bot_token": "MTQ3...***",
"asana_workspace_gid": "987654321",
"discord_guild_id": "1058318315564576848",
"scanner_roots": ["/data"],
"log_level": "info"
}
Secrets are masked: first 8 chars + ***. Use --redact=false for full values (debugging only).
mesh config init [path] — Generate starter config.yaml
mesh config init [path] [--format json]
Creates config.yaml (or specified path) with commented defaults. Fails if file already exists.
mesh config validate — Validate config file
mesh config validate [--live] [--format json]
| Flag | Default | Description |
|---|---|---|
--live |
false |
Test API credentials against live services |
Without --live: Validates YAML structure, required fields, CHECK-safe values.
With --live: Additionally tests:
- Asana PAT:
GET /users/me— confirms token works, prints workspace name - Discord token:
GET /users/@me— confirms bot token works, prints bot username - DB: opens and runs
PRAGMA integrity_check - Scanner roots: verifies paths exist and are readable
JSON output:
{
"valid": true,
"checks": {
"yaml": "ok",
"db": "ok",
"asana": {"status": "ok", "user": "Verious", "workspace": "My Workspace"},
"discord": {"status": "ok", "bot": "Flow Mesh#1234", "guild": "My Server"},
"scanner_roots": [{"path": "/data", "status": "ok", "readable": true}]
}
}
On failure:
{
"valid": false,
"checks": {
"yaml": "ok",
"asana": {"status": "error", "error": "401 Unauthorized"},
"discord": {"status": "ok", "bot": "Flow Mesh#1234"}
}
}
mesh config get <key> — Read a single config value
mesh config get <key> [--format json]
Dot-notation for nested keys:
mesh config get listen_addr # → 127.0.0.1:8300
mesh config get asana_workspace_gid # → 987654321
mesh config get auto_mesh.enabled # → true
mesh config get scanner_roots # → ["/data"]
mesh config get asana_pat # → 1/12345...*** (redacted)
mesh config get asana_pat --redact=false # → full token
JSON output:
{"key": "listen_addr", "value": "127.0.0.1:8300"}
Unknown key → exit 1 with "unknown config key: foo".
mesh config set <key> <value> — Write a single config value
mesh config set <key> <value> [--format json]
Writes to config.yaml, preserving existing structure. Supports dot-notation.
mesh config set listen_addr 0.0.0.0:8300
mesh config set log_level debug
mesh config set auto_mesh.enabled true
mesh config set auto_mesh.poll_interval_seconds 120
mesh config set scanner_roots '["/data","/home"]' # JSON array
Behavior:
- Reads existing config.yaml.
- Updates the specified key (creates nested keys if needed).
- Writes back with preserved YAML structure.
- Re-validates the config after write.
JSON output:
{"key": "listen_addr", "value": "0.0.0.0:8300", "previous": "127.0.0.1:8300"}
Rejected keys: Cannot set db_path (requires restart). Cannot set secrets via config set — use config set-secret instead.
mesh config set-secret <key> — Set a secret interactively
mesh config set-secret <key>
Prompts for value on stdin (no echo). Writes to config.yaml.
Valid keys: asana_pat, discord_bot_token, asana_client_secret.
mesh config set-secret asana_pat
# Enter value: ********
# ✓ asana_pat updated
For non-interactive (piped) usage:
echo "1/12345..." | mesh config set-secret asana_pat
mesh auth
Manage app-level authentication users. Users are stored in the kv table with auth_user:<name> keys.
mesh auth create-user <username> <password>
mesh auth create-user <username> <password> [--format json]
Creates a new user with bcrypt-hashed password. Fails if user already exists.
mesh auth create-user admin mypassword
# ✓ Created user: admin
mesh auth create-user deploy-bot 'S3cur3!' --format json
# {"created": "deploy-bot"}
Behavior:
- Validates username (alphanumeric + hyphens, 1-64 chars).
- Hashes password with bcrypt (cost 10).
- Stores
auth_user:admin→ hash inkvtable. - If first user: also sets
auth_hmac_secretif not present.
mesh auth reset-password <username> <new-password>
mesh auth reset-password <username> <new-password> [--format json]
Resets password for existing user. Fails if user doesn't exist.
mesh auth reset-password admin newpassword123
# ✓ Password reset for: admin
mesh auth list-users
mesh auth list-users [--format json]
Lists all configured users (no passwords shown).
mesh auth list-users
# admin
# deploy-bot
mesh auth list-users --format json
# {"users": ["admin", "deploy-bot"], "count": 2}
mesh auth delete-user <username>
mesh auth delete-user <username> [--format json]
Removes a user. Fails if user doesn't exist. Warns if deleting the last user (auth will be disabled).
mesh auth delete-user deploy-bot
# ✓ Deleted user: deploy-bot
mesh auth delete-user admin
# ⚠ Warning: admin is the last user. Deleting will disable authentication.
# ✓ Deleted user: admin
mesh setup
Generate reverse proxy configurations.
mesh setup nginx — Nginx config
mesh setup caddy — Caddyfile
mesh setup cloudflared — Cloudflare tunnel config
mesh auto-mesh
Watched-folder auto-detection management.
| Subcommand | Description |
|---|---|
status |
Show auto-mesh config and folder counts |
enable / disable |
Toggle auto-mesh on/off |
set-interval <seconds> |
Set poll interval (minimum 5s) |
add-folder PATH [--template T] |
Watch a directory (validates path, checks overlap) |
remove-folder PATH |
Stop watching a directory |
enable-folder PATH |
Re-enable a disabled folder |
disable-folder PATH |
Disable without removing |
list-folders |
List watched folders with enabled state |
templates |
List available templates with all policy fields |
create-template <name> [flags] |
Create a new template |
update-template <name> [flags] |
Update template fields |
delete-template <name> |
Delete (rejects default, rejects if in use) |
poll |
Force an immediate poll cycle |
Template flags (for create-template / update-template)
--sync-mode MODE bidirectional, asana_to_beads, beads_to_asana
--comment-mode MODE full_projection, inline_only, none
--approval-mode MODE none, required_for_creates, required_for_creates_and_moves, required_for_all_writes
--subtask-mode MODE mirror, flatten, ignore
--drift-mode MODE auto, prompt, ignore
--no-asana Disable Asana representation
--no-discord Disable Discord representation
Examples
# Full setup from CLI
mesh auto-mesh enable
mesh auto-mesh set-interval 30
mesh auto-mesh create-template ci-projects --sync-mode bidirectional --approval-mode none
mesh auto-mesh add-folder /data/projects --template ci-projects
mesh auto-mesh poll --format json
# Manage folders
mesh auto-mesh disable-folder /data/projects # pause without removing
mesh auto-mesh enable-folder /data/projects # re-enable
mesh auto-mesh list-folders --format json
# Template lifecycle
mesh auto-mesh update-template ci-projects --drift-mode auto
mesh auto-mesh delete-template ci-projects # fails if folders use it
mesh ask
One-shot intelligence query.
mesh ask "show me task status" [--format json]
mesh chat
Interactive intelligence chat loop.
mesh chat [--format json]
mesh mcp
Start MCP server on stdio. Single tool mesh_run routes to all CLI commands.
mesh mcp
mesh scan
Scan filesystem for git repos.
mesh scan [ROOT] [--config path] [--format json]
mesh version
mesh version
Output: flow-mesh 0.2.0
mesh onboard
The supported clean-install path. Creates the installation identity, the trial marker, the provider binding, the first project space, and the first work item with its ledger event. No configuration file has to be written by hand.
mesh onboard [flags]
| Flag | Default | Description |
|---|---|---|
--project |
Flow Mesh |
Display name of the first project space |
--origin |
mesh |
Origin of the first project space |
--task |
Prove the mesh synchronizes |
Title of the first task |
--provider |
(none) | Provider to bind, e.g. discord. Omit for a keyless install |
--credential-type |
bot_token |
One of pat, oauth2, api_key, bot_token |
--credential-ref |
(none) | Path to the credential file; the value is never read into output |
--url |
(none) | Public URL of this mesh, shown to the operator |
--diagnose |
off | Read-only: report the blocking step, code, stopped dependents, and repair |
--reconnect |
off | Replace the provider credential on a ready install |
--revoke |
off | Remove the provider binding; project and tasks survive |
Output is a JSON report: status, phase, steps, executed, skipped, ready, elapsed_ms, install_id, data_root, external_url. Recovery verbs also report receipt; a blocked run additionally reports error and a recovery object with blocked_at, code, retryable, stopped, and action.
Exit codes:
| Code | Meaning |
|---|---|
0 |
ready — the install reached its first synchronized task |
1 |
blocked or failed; the JSON body names the repair |
Data root is selected with FLOW_MESH_DATA_DIR or --config.
# clean install
FLOW_MESH_DATA_DIR=/srv/flow-mesh mesh onboard --provider discord \
--credential-ref /etc/flow-mesh/discord-bot-token
# what is blocking this install
mesh onboard --diagnose
# rotate a provider credential without touching project or tasks
mesh onboard --reconnect --provider discord --credential-ref /etc/flow-mesh/discord-bot-token
# disconnect a provider; the install stays usable
mesh onboard --revoke --provider discord
Agent Workflow Examples
Create a full mesh with all channels syncing
# Create mesh linked to repo + Asana + Discord, template B (bidirectional), activate immediately
mesh ps create "My New Project" \
--repo /data/my-project \
--asana-create \
--discord-create \
--template B \
--activate \
--format json
# Output: {"mesh_id":"019c...","name":"My New Project","state":"active",...}
Full lifecycle from agent perspective
# 1. Create mesh
MESH=$(mesh ps create "Sprint 42" --repo /data/sprint42 --asana-create --discord-create --template B --activate --format json | jq -r .mesh_id)
# 2. Import existing tasks
mesh ps import $MESH --format json
# 3. Create tasks
mesh task create "Implement auth" --mesh $MESH --status ready --priority P1 --format json
mesh task create "Write tests" --mesh $MESH --status backlog --priority P2 --format json
# 4. Trigger sync (push to Asana + Discord)
mesh sync $MESH --format json
# 5. Check for conflicts
mesh conflicts --mesh $MESH --format json
# 6. Update task status
TASK=$(mesh task list --mesh $MESH --status ready --format json | jq -r '.items[0].id')
mesh task update $TASK --status in_progress --format json
# 7. Sync again
mesh sync $MESH --format json
# 8. Check drift
mesh drift $MESH --format json
# 9. Close task
mesh task close $TASK --format json
# 10. Final sync
mesh sync $MESH --format json
# 11. Export snapshot
mesh export snapshot --format json > backup.json
# 12. Pause mesh when done
mesh ps pause $MESH
Via MCP (for agents that prefer tool calls)
{"command": "ps create \"Sprint 42\" --repo /data/sprint42 --asana-create --discord-create --template B --activate --format json"}
{"command": "task create \"Implement auth\" --mesh 019c... --status ready --priority P1 --format json"}
{"command": "sync 019c... --format json"}
§O Observability Contract
Iron rule: Every mutating CLI operation MUST be visible in the web UI Events page. No silent mutations. If it changes state, it logs an event. Period.
Event Ledger Schema (recap)
Every CLI event inserts one row into event_ledger:
| Column | CLI Value | Description |
|---|---|---|
event_id |
UUIDv7 | Unique event ID |
project_space_id |
mesh ID or _global |
Which mesh this event belongs to |
source_system |
"mesh" |
Always mesh for CLI operations |
source_entity_id |
context-dependent | The entity acted upon (mesh ID, work item ID, etc.) |
event_type |
see table below | Canonical event type |
actor_type |
"system" |
CLI is a system actor |
actor_id |
"cli" |
Distinguishes CLI from UI ("ui") and webhooks ("webhook") |
payload |
JSON object | Structured KV pairs with operation details |
occurred_at |
UTC timestamp | When the operation happened |
ingested_at |
UTC timestamp | Same as occurred_at for direct inserts |
idempotency_key |
same as event_id | Prevents duplicate processing |
projected_targets |
"{}" |
CLI events are pre-projected (no outbound sync needed for the event itself) |
projection_state |
"projected" |
Already applied |
Event Type × Command Matrix
Every mutating command and the exact event(s) it MUST log:
| Command | Event Type | source_entity_id |
Payload Keys |
|---|---|---|---|
mesh ps create |
create |
new mesh ID | name, template, state |
mesh ps create --repo |
representation_link |
mesh ID | action=link, type=server, repo_path |
mesh ps create --asana |
representation_link |
mesh ID | action=link, type=asana, project_gid |
mesh ps create --asana-create |
representation_link |
mesh ID | action=create, type=asana, project_gid |
mesh ps create --discord |
representation_link |
mesh ID | action=link, type=discord, channel_id |
mesh ps create --discord-create |
representation_link |
mesh ID | action=create, type=discord, channel_id |
mesh ps create --activate |
status_change |
mesh ID | from=configured, to=active |
mesh ps delete |
delete |
mesh ID | name, cascade=true |
mesh ps activate |
status_change |
mesh ID | from=<old>, to=active |
mesh ps pause |
status_change |
mesh ID | from=<old>, to=paused |
mesh ps link --repo |
representation_link |
mesh ID | action=link, type=server, repo_path |
mesh ps link --asana |
representation_link |
mesh ID | action=link, type=asana, project_gid |
mesh ps link --asana-create |
representation_link |
mesh ID | action=create, type=asana, project_gid |
mesh ps link --discord |
representation_link |
mesh ID | action=link, type=discord, channel_id |
mesh ps link --discord-create |
representation_link |
mesh ID | action=create, type=discord, channel_id |
mesh ps unlink --repo |
representation_unlink |
mesh ID | type=server |
mesh ps unlink --asana |
representation_unlink |
mesh ID | type=asana |
mesh ps unlink --discord |
representation_unlink |
mesh ID | type=discord |
mesh ps import |
import |
mesh ID | mode, items_imported |
mesh task create |
work_item_create |
mesh ID | work_item_id, title, status, priority |
mesh task update |
work_item_update |
mesh ID | work_item_id, fields changed |
mesh task close |
work_item_update |
mesh ID | work_item_id, status=done |
mesh sync |
status_change |
mesh ID | action=manual_sync, ingested, projected |
mesh drift --fix |
update |
mesh ID | action=drift_repair, fixed_count |
Non-mutating commands do NOT log events: list, show, status, events, conflicts, scan, export, providers, config show, config validate, version, help.
UI Visibility
The Events page (/events) displays all ledger entries with:
- Filter by actor:
?actor=clishows only CLI operations. - Filter by source:
?source=meshshows all mesh-originated events (CLI + UI + auto-mesh). - Filter by type:
?type=createshows all mesh creations regardless of actor. - Filter by mesh:
?ps=019c...shows all events for a specific mesh. - Payload expansion: Each event row is expandable to show the full JSON payload with all KV pairs.
An agent or human can verify any CLI operation by visiting:
https://mesh.example.com/events?actor=cli
Dashboard Visibility
The dashboard (/) shows:
- Recent events feed (last 8 events) — CLI events appear here immediately.
- Pending/failed counts — CLI-triggered sync failures appear as failed events.
- Per-mesh stats — work item counts update after CLI task creates.
- Active/configured/paused/error mesh counts — state changes from CLI reflected immediately.
Mesh Detail Visibility
The mesh detail page (/project-spaces/<id>) shows:
- Event count for that specific mesh — includes all CLI events targeting it.
- Linked representations — updated after
mesh ps link/unlink. - Policy settings — reflect template from
mesh ps create. - Work items — tasks created via CLI appear in the work items section.
- Import results —
mesh ps importresults visible. - Drift scan results —
mesh driftresults visible.
logCLIEvent Helper
All CLI event logging goes through a single helper to ensure consistency:
// logCLIEvent inserts a pre-projected event into the ledger.
// Called by every mutating CLI command. Panics on DB error (fail-loud).
func logCLIEvent(db *sql.DB, psID string, eventType mesh.EventType, kv ...string) {
eid := mesh.NewUUIDv7()
payload := kvToJSON(kv)
now := time.Now().UTC().Format(time.RFC3339)
_, err := db.Exec(`INSERT INTO event_ledger
(event_id, project_space_id, source_system, source_entity_id,
event_type, actor_type, actor_id, payload,
occurred_at, ingested_at, idempotency_key,
projected_targets, projection_state)
VALUES (?, ?, 'mesh', ?, ?, 'system', 'cli', ?, ?, ?, ?, '{}', 'projected')`,
eid, psID, psID, string(eventType), string(payload), now, now, eid)
if err != nil {
log.Printf("WARNING: event log failed: %v", err)
}
}
// kvToJSON converts variadic key-value pairs to JSON payload.
func kvToJSON(kv []string) []byte {
if len(kv) == 0 { return []byte("{}") }
m := make(map[string]string, len(kv)/2)
for i := 0; i+1 < len(kv); i += 2 {
m[kv[i]] = kv[i+1]
}
b, _ := json.Marshal(m)
return b
}
Observability Verification Test
After implementing all CLI commands, run this verification:
# 1. Create a mesh via CLI
MESH=$(mesh ps create "Observability Test" --repo /tmp/obs-test --template B --activate --format json | jq -r .mesh_id)
# 2. Create a task via CLI
TASK=$(mesh task create "Test task" --mesh $MESH --priority P1 --format json | jq -r .work_item_id)
# 3. Update via CLI
mesh task update $TASK --status in_progress --format json
# 4. Verify ALL operations visible in event ledger
EVENTS=$(mesh events --ps $MESH --format json | jq length)
# Expected: at least 4 events (create mesh, link repo, activate, create task, update task)
# 5. Verify via UI — curl the events page filtered to this mesh
curl -s -b cookies "https://mesh.example.com/events?ps=$MESH&actor=cli" | grep -c "cli"
# Expected: matches $EVENTS count
# 6. Cleanup
mesh ps delete $MESH --format json
Implementation Notes
Shared Helpers (main.go)
// Global state set in main() before dispatch
var globalJSON bool // --format json
func loadCfg(args []string) *config.Config // parse --config, load YAML + env
func openDB(cfg *config.Config) *db.DB // open + migrate
func cfgPath(args []string) string // extract --config value
// Output helpers
func writeJSONOut(v interface{}) // json.Encoder to stdout
func logCLIEvent(d *sql.DB, psID string, eventType mesh.EventType, kv ...string)
func kvToJSON(kv []string) []byte
State Machine
All state transitions in mesh ps activate|pause MUST use mesh.CanTransition():
detected → configured, ignored
configured → active, paused, ignored
active → paused, ignored, error
paused → active, ignored, error
ignored → detected
error → paused, active, ignored
Foreign Key Safety
mesh task create MUST validate --mesh exists before INSERT:
var exists int
d.QueryRow(`SELECT COUNT(*) FROM project_spaces WHERE project_space_id = ?`, meshID).Scan(&exists)
if exists == 0 {
log.Fatalf("mesh not found: %s", meshID)
}
mesh resolve
Resolve a detected conflict.
mesh resolve CONFLICT_ID --winner asana|beads|discord [--format json] [--config PATH]
| Flag | Description |
|---|---|
CONFLICT_ID |
The conflict event ID from mesh events --type conflict |
--winner |
Which system's value wins (asana, beads, or discord) |
--format json |
JSON output |
Behavior:
- Updates
event_ledgerconflict event payload with resolution - Updates
work_itemswith winning value - Logs a
conflict_resolvedevent
mesh resolve evt-019414d6 --winner asana
mesh resolve evt-019414d6 --winner discord --format json
mesh intel
Intelligence layer commands.
mesh intel decompose
Manually trigger auto-decomposition on a work item.
mesh intel decompose WORK_ITEM_ID [--dry-run] [--mesh MESH_ID] [--all] [--format json]
| Flag | Description |
|---|---|
WORK_ITEM_ID |
Work item to decompose |
--dry-run |
Show plan without creating subtasks |
--mesh MESH_ID |
Scope to specific mesh |
--all |
Decompose all eligible items in mesh |
mesh intel status
Show intelligence engine status.
mesh intel status [--format json]
Displays: enabled, provider, model, spending, active delegations.
mesh intel ask
One-shot question to the intelligence engine (alias: mesh ask).
mesh intel ask "QUESTION" [--mesh MESH_ID] [--format json]
mesh intel chat
Interactive chat loop with the intelligence engine.
mesh intel chat [--mesh MESH_ID]
mesh license
License management commands.
mesh license activate KEY # Activate a license key
mesh license status # Show current license tier, limits, expiry
mesh license deactivate # Remove license key (install locks when trial is over)
mesh authority
Portable self-hosted authority bootstrap. Commands never print private keys or grants; they write caller-selected files and return bounded JSON receipts.
mesh authority keygen --private-key-file PATH --public-key-file PATH
mesh authority grant --private-key-file PATH --output PATH \
--subject ID --audience URL --providers google_tasks \
--operations oauth.broker --ttl 720h
# Official CLI is preferred; a local loopback browser recipe is selected for
# provider-console-only operations. Request and recipe files contain references,
# never credential values.
mesh authority provision --request REQUEST.json \
--grant-file GRANT --public-key-file PUBLIC_KEY --audience AUDIENCE \
[--recipe config/provider-recipes/PROVIDER.v1.json] \
[--cdp-endpoint http://127.0.0.1:9222]
# Starts a deployment-owned Chromium profile with loopback-only automation.
scripts/provider-console-browser.sh
# Creates/reuses a deployment-owned browser profile, verifies a scoped grant,
# and authenticates without putting credential values in process arguments.
FLOW_MESH_PROVIDER_BROWSER_MODE=headless scripts/provider-session-auth.sh \
--provider PROVIDER --recipe RECIPE.json \
--email-file /run/secrets/provider-email \
--password-file /run/secrets/provider-password \
--profile /var/lib/flow-mesh/provider-browser/PROVIDER
Ready-to-copy requests are under `examples/provider-provisioning/`; built-in
versioned recipes are under `config/provider-recipes/`.
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | User error (bad args, not found, validation failure) |
| 2 | System error (DB failure, API unreachable) |
License errors (exit 1, printed as Error [CODE])
| Code | Meaning |
|---|---|
| E041 | Mesh limit reached for the tier — activate a license to raise it |
| E042 | Trial expired with no key — install is locked; buy and activate a key |