Flow Mesh CLI Specification

Status: Definitive spec. Implementation MUST match this document. Audience: Developers, AI agents, CI/CD pipelines.


Design Principles

  1. Agent-first. Every operation available in the UI is available via CLI with --format json output. Zero context cost for AI agents — no MCP needed for basic workflows.
  2. Single binary. mesh <command> [subcommand] [flags]. No daemon required for read operations (reads DB directly). serve starts the HTTP server + sync engine.
  3. Predictable flags. Global flags parsed before dispatch. Per-command flags after the subcommand. --config always works. --format json always works.
  4. Safe defaults. Destructive operations require explicit IDs. No silent data loss. FK constraints validated before INSERT.
  5. Composable. Every command that produces output supports --format json for 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:

  1. Generates UUIDv7 for project_space_id.
  2. Inserts into project_spaces with state configured.
  3. If --repo: validates path exists, has .git/, inserts into project_space_server. Detects beads.
  4. If --asana GID: inserts into project_space_asana.
  5. If --asana-create: calls Asana API to create project + custom fields, inserts mapping.
  6. If --discord ID: inserts into project_space_discord with mode full.
  7. If --discord-create: calls Discord API to create forum channel, pins metadata, inserts mapping.
  8. Inserts project_space_policy based on template, with representation flags matching what was linked.
  9. If --activate: transitions state to active.
  10. Logs create event to event_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:

  1. Validates mesh exists.
  2. Rejects _global (cannot delete).
  3. Deletes from: project_space_policy, project_space_server, project_space_asana, project_space_discord, work_items, approvals, event_ledger, project_spaces.
  4. 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]

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_policy representation flags.
  • Logs representation_link event.
  • If --asana-create: creates Asana project via API, adds custom fields.
  • If --discord-create: creates Discord forum channel, pins metadata message.

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, or project_space_discord).
  • Updates project_space_policy representation flag to off.
  • Logs representation_unlink event.
  • 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_items in the DB.
  • Logs import event 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:

  1. Validates --mesh exists in project_spaces (prevents FK crash).
  2. Validates --status and --priority against CHECK constraints.
  3. Inserts into work_items.
  4. Logs work_item_create event.

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 as Last-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.stream resumes on (occurred_at, event_id) and progress-stream on (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: resync with reason: cursor_not_found and 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-alive comments, 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 <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:

  1. Scans env vars for LLM API keys (Anthropic, OpenAI, Kimi, OpenRouter, Ollama)
  2. Scans for tools (cloudflared, pi, bd, git, docker)
  3. Checks port 8300, OS, init system
  4. Tests LLM connectivity with ping
  5. If --auto: stores LLM config, creates admin user
  6. 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:

  1. If mesh ID given: validates mesh exists and is active.
  2. Runs one cycle of: poll beads → ingest events → project pending events.
  3. 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:

  1. For each active mesh (or specified mesh): compare work items across linked representations.
  2. Report field-level drifts.
  3. 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:

  1. Reads existing config.yaml.
  2. Updates the specified key (creates nested keys if needed).
  3. Writes back with preserved YAML structure.
  4. 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:

  1. Validates username (alphanumeric + hyphens, 1-64 chars).
  2. Hashes password with bcrypt (cost 10).
  3. Stores auth_user:admin → hash in kv table.
  4. If first user: also sets auth_hmac_secret if 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=cli shows only CLI operations.
  • Filter by source: ?source=mesh shows all mesh-originated events (CLI + UI + auto-mesh).
  • Filter by type: ?type=create shows 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 import results visible.
  • Drift scan results — mesh drift results 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_ledger conflict event payload with resolution
  • Updates work_items with winning value
  • Logs a conflict_resolved event
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

Generated from the Flow Mesh repository by scripts/build-docs-site.sh. If a page is wrong here, the file it was rendered from is wrong.