@syntropic137/cli

Command-line interface for Syntropic137 — an event-sourced workflow engine for AI agents.

Design

Single dependency. 168 KB. Full API coverage.

The CLI is built with a zero-dependency philosophy:

• No Commander.js — custom two-level command framework on node:parseArgs
• No chalk — direct ANSI escape codes with NO_COLOR support
• No axios — built-in fetch with timeout and streaming (SSE)
• One runtime dep — Zod for local file validation only

The entire CLI ships as a single dist/syn.mjs file (168 KB). It targets Node.js 22+ with strict TypeScript (noUncheckedIndexedAccess, exactOptionalPropertyTypes).

API response types are generated from the OpenAPI spec, so the TypeScript compiler catches any API drift at build time.

Install

npm install -g @syntropic137/cli

Or run directly:

npx @syntropic137/cli health

Connect to a Server

By default, the CLI connects to http://localhost:8137 (local dev server).

Local

# Start the API server
just dev

# Use the CLI — no auth needed on localhost
syn health
syn workflow list

Remote

Set the server URL and credentials:

export SYN_API_URL=https://syn.example.com
export SYN_API_USER=admin
export SYN_API_PASSWORD=your-password

syn health

Or use a bearer token:

export SYN_API_URL=https://syn.example.com
export SYN_API_TOKEN=your-token

syn health

Environment variables take precedence. When no credentials are set, requests are sent without authentication (suitable for localhost).

Commands

Root Commands

| Command | Description | |---------|-------------| | syn health | Check API server health | | syn version | Show CLI version | | syn run <workflow> | Execute a workflow (shortcut) |

Workflow Management

syn workflow list                    # List all workflows
syn workflow show <id>               # Show workflow details
syn workflow create <name>           # Create a new workflow
syn workflow run <id> -i key=value   # Execute a workflow
syn workflow status <id>             # Show execution history
syn workflow validate <path>         # Validate a workflow package
syn workflow delete <id> --force     # Archive a workflow
syn workflow export <id> -o ./out    # Export workflow files

Workflow Packages & Marketplace

# Install from marketplace, git, or local path
syn workflow install my-plugin
syn workflow install https://github.com/org/repo
syn workflow install ./local-package

# Manage installations
syn workflow installed               # List installed packages
syn workflow update my-plugin        # Update to latest
syn workflow uninstall my-plugin     # Remove workflows

# Search the marketplace
syn workflow search "code review"
syn workflow info my-plugin

# Manage registries
syn marketplace add https://github.com/org/registry
syn marketplace list
syn marketplace refresh

Execution Control

syn execution list                   # List all executions
syn execution show <id>              # Show execution detail

syn control pause <id>               # Pause at next yield point
syn control resume <id>              # Resume paused execution
syn control cancel <id> --force      # Cancel execution
syn control status <id>              # Check execution state
syn control inject <id> -m "msg"     # Inject a message

Sessions & Observability

syn sessions list                    # List agent sessions
syn sessions show <id>               # Show session detail

syn events recent                    # Recent domain events
syn events session <id>              # Session events
syn events timeline <id>             # Tool-call timeline
syn events costs <id>                # Token/cost breakdown
syn events tools <id>                # Tool usage summary

syn observe tools <id>               # Tool execution timeline
syn observe tokens <id>              # Token breakdown

syn conversations show <id>          # View conversation log
syn conversations metadata <id>     # Conversation metadata

Cost Tracking

syn costs summary                    # Global cost overview
syn costs sessions                   # Cost by session
syn costs session <id>               # Session cost detail
syn costs executions                 # Cost by execution
syn costs execution <id>             # Execution cost detail

Organization Management

syn org create --name "Acme"         # Create organization
syn org list                         # List organizations
syn org show <id>                    # Organization detail

syn system create --name "Backend"   # Create system
syn system list                      # List systems
syn system status <id>               # System health
syn system cost <id>                 # System costs
syn system patterns <id>             # Failure patterns
syn system history <id>              # Execution history

syn repo register --url owner/repo   # Register repository
syn repo list                        # List repositories
syn repo health <id>                 # Health metrics
syn repo cost <id>                   # Cost breakdown
syn repo activity <id>               # Recent activity
syn repo failures <id>               # Recent failures

Live Streaming

syn watch execution <id>             # Stream execution events (SSE)
syn watch activity                   # Stream all activity

Triggers

syn triggers register --repo r --workflow w --event push
syn triggers enable self-healing --repo r
syn triggers list
syn triggers show <id>
syn triggers history <id>
syn triggers pause <id>
syn triggers delete <id> --force

Configuration & Metrics

syn config show                      # Show current config
syn config validate                  # Validate configuration
syn metrics show                     # Aggregated metrics
syn insights overview                # Global system overview
syn insights cost --days 30          # Cost analysis
syn insights heatmap                 # Activity heatmap

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | SYN_API_URL | http://localhost:8137 | API server URL | | SYN_API_TOKEN | — | Bearer token for authentication | | SYN_API_USER | — | Basic auth username | | SYN_API_PASSWORD | — | Basic auth password | | NO_COLOR | — | Disable colored output |

Development

# Install dependencies
pnpm install

# Development mode (auto-reload)
pnpm dev

# Build
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

# Regenerate API types from OpenAPI spec
pnpm generate:types

# Check for API drift (CI)
pnpm check:api-drift

API Type Safety

All commands use the typed API client powered by openapi-fetch. Response types are generated from the OpenAPI spec (apps/syn-docs/openapi.json) using openapi-typescript, giving compile-time path validation and fully typed responses.

import { api, unwrap } from "../client/typed.js";
import type { components } from "../generated/api-types.js";

type ExecutionList = components["schemas"]["ExecutionListResponse"];

const data = unwrap(
  await api.GET("/executions", { params: { query: { status: "running" } } }),
  "List executions",
);
// data.executions is typed as ExecutionSummaryResponse[]
// data.total is typed as number

If the API spec changes:

1. pnpm generate:types regenerates the types
2. tsc catches any CLI code that doesn't match the new schema
3. pnpm check:api-drift in CI flags stale generated types
4. pnpm check:untyped-api in CI prevents use of the deprecated untyped client

License

MIT