smesh CLI reference

Every smesh command, flag, and exit code.

smesh is the short command name for Skilak Mesh. This specification defines the individual-user install, setup, daily operation, enforcement, and support experience. Every command-shaped example and command-reference entry below is part of the current parser surface. Future capabilities are described without command syntax until they are implemented.

Product principles

1. A new individual user should reach a healthy local text gateway and Dashboard Lite without cybersecurity expertise.
2. Setup must say exactly which clients are routed, blocked, or untouched. “Installed” must never be presented as “all AI traffic protected.”
3. Every client edit and privileged enforcement change must be previewed, backed up, verified, and reversible.
4. Provider credentials belong in the OS credential store and must never be printed, written to ordinary config, included in logs, or included in a support bundle.
5. Terms/license acceptance is explicit and versioned, but must not silently enable telemetry or data collection.
6. Scanner failures block by default. The CLI must explain that fail-closed protection can interrupt work.

Client state always separates installed, supported, configured, connected, gateway healthy, and protected now. No state is promoted from the existence of a config file.

Protection posture has three values. Protected requires the exact current managed route generation, a healthy gateway, no restart debt, and an audited scanned request from that generation within the last 15 minutes. Not protected requires positive evidence that protection is unavailable, such as a removed/displaced setting or an unhealthy gateway; only configuration drift is called a takeover. Unknown / not verified covers unreadable state and a correctly configured but idle client. Missing, older, or implausibly future traffic evidence is suspicion, never takeover proof.

Packaging

The first macOS beta should be distributed through a Homebrew tap:

brew install skilaklabs/tap/smesh
smesh init

This is the target flow, not current artifact availability. It becomes usable only after the operator publishes the reviewed private Formula and its release assets; no native macOS runner is currently registered.

The current Formula template installs the Python management CLI in an isolated Homebrew virtual environment. The CLI orchestrates pinned Skilak Mesh container images because the runtime contains Python services, OCR/barcode utilities, and document/image parsers. A future native DMG is a separate gated artifact. npm is not the primary distribution channel: a Node package does not solve the runtime, service, OS credential-store, upgrade, or privileged network control requirements.

smesh init may offer to install/start Colima through Homebrew when no supported container runtime is present, but it must show the action and ask first. It must never request Docker-socket access for an AI coding agent.

First-run flow

Running smesh init without flags starts an interactive wizard. It creates no network or client changes until the user reaches the final Apply step.

1. Welcome and boundary

The first screen explains:

• Skilak Mesh scans the AI requests routed through it and resolves findings to one of four verdicts: allow, warn, redact, or block;
• unknown provider paths are forwarded only when their request representation is fully enumerable; their path segments and query strings are scanned too;
• provider files are enabled by default with provider-alias- and revision-bound reuse through recognized JSON file-ID fields; assistants, batches, containers, conversations, fine-tuning, threads, uploads, and vector stores default off and can be enabled only with their validated provider_storage.<prefix> switch;
• it does not inspect what the provider sends back — responses are relayed to the client unmodified — and it is not an output filter;
• it cannot prevent an AI agent from reading a local secret—agent permissions and filesystem isolation remain necessary;
• unsupported desktop/vendor apps cannot be transparently redirected and may be blocked only if the user enables enforcement; and
• this beta is source-available, fair-source software under BUSL-1.1.

2. Terms, privacy, and license

The wizard shows links/paths to the exact bundled versions of:

• BUSL-1.1 LICENSE;
• the commercial-license summary;
• CLI/software terms; and
• privacy policy.

It then asks the user to classify the installation:

How will this installation be used?
  1. Individual use
  2. Evaluation, development, testing, or research
  3. Organization production/commercial use

Choices 1 and 2 fall under the Additional Use Grant, subject to the BUSL terms. Choice 3 requires commercial entitlement and sends the user to licensing@skilakconsulting.com or skilakmesh.com; setup must not invent a price. The binding agreement and click-through implementation require a lawyer’s approval before release.

Consent is separate and explicit:

[ ] I agree to Skilak Mesh Terms version <version>.
[ ] I acknowledge the applicable BUSL-1.1/commercial licensing terms.
[ ] I understand fail-closed scanning can block or delay AI requests.

The local acceptance record contains only document identifiers, document digests, accepted timestamp, selected usage class, CLI version, and a random installation ID. It contains no name, email, prompt, credential, machine fingerprint, or telemetry identifier and is not transmitted automatically. If terms materially change, the next interactive upgrade asks again before enabling the new version. Security-only upgrades may be installed without new terms acceptance when the legal document digests are unchanged.

Non-interactive provisioning requires explicit versions rather than a generic --yes:

smesh init --non-interactive \
  --usage individual \
  --accept-terms <terms-version> \
  --ack-license <license-digest> \
  --profile strict --files deny

3. Preflight

The wizard checks, without printing environment variables or secret files:

• supported macOS/CPU and free disk/memory;
• Homebrew and a supported container runtime;
• loopback ports and local DNS behavior;
• image availability/signature and minimum supported versions;
• writable, permission-restricted config/data locations; and
• whether an older Skilak Mesh install needs migration.

Proposed locations:

~/.config/skilakmesh/       non-secret configuration and acceptance records
~/Library/Application Support/SkilakMesh/  audit DB and runtime state
macOS Keychain              provider credentials and locally generated keys

No actual credential value appears in smesh config show, logs, process arguments, shell history, or support bundles.

4. Protection profile

The user chooses:

• Strict — recognized credentials and broad high-entropy/opaque detections block;
• Balanced — recognized credentials in reviewed ordinary conversation text are redacted and the complete rewritten request is rescanned; unsupported carriers block, while selected broad heuristic findings warn; or
• Custom — start from a preset and open the policy editor/validator.

File mode is a separate choice:

• Deny files — recommended for an early beta and highest predictability;
• Inspect supported files — PDFs, images, Office documents, archives, and other documented types are scanned within limits when included in a request; supported Office documents inside archives are scanned recursively; unsupported files block. Downloads are not inspected;
• Deny images only — allow supported text/document files but block images.

The wizard must not offer a silent “allow unscannable files” option.

5. Providers

For each selected provider, init asks for an API credential using hidden input, stores it in macOS Keychain, and immediately clears the in-memory input after passing it to the local runtime. The user can choose:

Provider                 Action
OpenAI                   Configure / Later
Anthropic                Configure / Later
Google-compatible route  Configure / Later
Local OpenAI-compatible  Configure URL / Later

The credential belongs to the user and is relayed to the pinned provider with their request; the gateway stores no provider credential of its own and must never be presented as holding one.

The test step performs a local configuration/health check first. A real provider call is always labeled as such and is opt-in because it can incur cost and send a synthetic request externally.

6. Clients and applications

Detection produces a review table; it does not modify anything yet. Every row uses these independent columns:

Inventory includes installed unsupported clients instead of omitting them. It names the missing seam or adapter and offers a safe routed alternative.

Two automatic adapters ship:

• Claude Code CLI settings; and
• shared Codex configuration, which can affect both Codex CLI and Codex in VS Code.

The Codex config file proves neither surface is installed or connected. A Codex plan names every detected affected surface before approval. Gemini CLI, AGY, AnythingLLM Desktop, and other compatible clients have no shipped adapter; their exact version and custom endpoint must be verified before manual setup. ChatGPT Desktop, Claude Desktop, and Gemini Desktop remain visible when installed and explain the approved routed alternative.

If the owned setting already contains another route, connect displays a bounded, credential-free rendering of that value and every affected surface. Generic --apply does not displace it. The user must add --replace-foreign-route, and the connector rechecks the reviewed file before writing. Known stable signatures may name the displacing tool; for example, Free Claude Code’s documented loopback route is named without showing its auth token. Unrelated settings are preserved.

After connect, the signed macOS controller watches the parent configuration directories so atomic-rename saves are visible, with a bounded periodic recheck as a backstop. A changed or removed exact managed generation revokes that generation’s route authority and opens one foreground Skilak Mesh alert per unchanged condition. The alert names the safe current value, known owner, all affected surfaces, and the recovery choice. It never rewrites the client setting. A payload-free, generation-bound gateway observation is a separate signal; its absence leaves posture unknown / not verified and never triggers a takeover alert. An observation expires after 15 minutes; expiration also returns posture to unknown / not verified, never not protected.

For every client the allowed actions are:

• Route through mesh — only when the installed version has a tested custom endpoint seam. The base URL written into a client config must carry the mesh’s /p/<alias>/ prefix (for example http://127.0.0.1:51737/p/anthropic); a bare host:port is refused by the gateway as unknown_provider_alias. Claude Code also requires ENABLE_TOOL_SEARCH=true: a base-only route is unsafe because it eagerly loads the user’s complete MCP schema catalog. The connector refuses settings or environment overrides that disable the deferred-tool protocol;
• Block direct use — only with enforcement enabled;
• Leave unchanged — clearly reported as unprotected; or
• Use approved local UI — install/configure a supported local UI such as Open WebUI or LibreChat against the mesh.

Before applying or removing a route, report any safely detected running client and require a full app or CLI restart. /clear and a new chat do not reload process configuration.

Each connector shows a diff, backs up the file it changes, refuses to overwrite an unknown/newer schema, tests with a fake local canary, and supports smesh client disconnect rollback. The CLI must not assume that a desktop app shares its companion CLI’s configuration.

For Claude Code 2.1.235, the tested custom-base protocol is advanced-tool-use-2025-11-20 plus deferred tool definitions and tool_reference blocks. Claude Code constructs the beta header; the connector does not forge one. The gateway must preserve the query, header, request body, and streamed response bytes for supported models before this connector may be enabled.

The captured client result block is {"type":"tool_result","tool_use_id":"...","content":[{"type":"tool_reference","tool_name":"..."}]}. The server content_block is {"type":"tool_search_tool_result","tool_use_id":"...","content":{"type":"tool_search_tool_search_result","tool_references":[{"type":"tool_reference","tool_name":"..."}]}}. Both shapes and the anthropic-beta value pass through byte-for-byte. An identified Claude Code request carrying claude-code-20250219 without advanced-tool-use-2025-11-20 is refused locally as claude_tool_search_unavailable, before its body is read or a provider is called. This fail-safe covers project/local settings and command-line tool denials that can override a persistent connector after it is applied.

7. Direct-egress enforcement

The user selects one of:

1. Routing only — no privileged network changes; easiest beta, but direct provider calls remain possible.
2. Observe — report known direct AI destinations/apps without blocking, subject to an explicit privacy disclosure about what local metadata is observed.
3. Enforce — require administrator approval and block known direct provider paths for non-mesh processes. Unsupported apps stop working; they are not redirected.

Before Enforce, smesh enforce plan must show the rules, affected detected apps, exclusions, recovery command, and a connectivity test. On macOS the long-term robust implementation is a signed Network Extension or a documented integration with an application-aware firewall. Raw IP-only pf rules are not enough for a reliable product because provider IPs change and are shared.

8. Dashboard Lite and retention

The individual beta enables a free dashboard bound to 127.0.0.1 by default. The wizard asks for retention by age/size and explains that audit metadata is sensitive even though prompts and matched values are not stored. It generates a local session token and offers smesh dashboard open.

9. Interruption and performance acknowledgement

Before Apply, setup presents these conditions:

• Clean text overhead: the repository’s July 18, 2026 pilot measured 18.62 ms added p95 over 50 loopback requests on one Mac. This excludes provider latency and is a benchmark, not a universal average or SLA.
• Interactive local decision target: for attachment-free JSON up to 128 KiB, measure from complete body receipt to response delivery. The supported-macOS gate is p95 at or below 500 ms and p99 at or below 1 second. The pre-provider audit-writer admission plus lock wait has a 150 ms deadline, isolated from scan workers, and still fails closed. CI enforces scaling and generous bounds; the operator benchmark enforces the absolute target. No detector is skipped or weakened to meet it.
• Attribution: the gateway attempts a payload-free timing record after each completed request, with stages for receive, parse, scan, policy, decision audit, provider wait, response delivery, response audit, and unassigned time. smesh events and the dashboard report p50, p95, and p99 by stage. A failed or saturated post-delivery timing write warns and is counted. Prompt text, matched values, content hashes, and file digests are excluded.
• Token streaming is preserved: ordinary provider responses are relayed to the client as they arrive and are not inspected, so streaming output appears token by token as it would without the mesh. A successful POST /files response is the bounded bookkeeping exception: it is parsed only to mint one file-ID attestation, not content-inspected.
• Files and images: parsing, OCR, archive expansion, QR/barcode decoding, and PDF rendering can take seconds. The current per-file ceiling is 45 seconds; timeout, unsupported, encrypted, oversized, or parser-failure cases block rather than forward uninspected. Supported files must be contained in a fully enumerable request. Provider file uploads are supported when provider_storage.files is enabled (the default); recognized provider-bound JSON file-ID fields require the current local attestation for the same alias.
• Fail-closed availability: representation, scanner, audit, or policy failures can interrupt AI calls. smesh status, smesh doctor, and smesh logs are the recovery path; bypassing the mesh is not presented as the fix.
• Enforcement impact: enabling direct-egress blocking can stop native AI apps, extensions, scripts, and CI jobs until they are routed or excluded.
• Cold start/update: initial image download and scanner startup can take minutes depending on network and machine speed. The CLI should show measured progress rather than promise a fixed duration.

10. Plan and Apply

init prints a final, non-secret plan covering runtime installation, provider entries, policy/file mode, client edits, enforcement, dashboard, and data locations. The user may save the plan, go back, or apply. Apply is transactional where possible: if health or client verification fails, it restores client and network changes and leaves diagnostic logs without credentials.

The successful final screen reports each boundary independently:

Gateway health:          healthy
Policy:                  strict, provider files enabled; other storage off
Codex CLI:               not installed; shared config present is not evidence
Codex in VS Code:        configured; restart required; connected not verified
Claude Code CLI:         configured; connected not verified
Claude Desktop:          installed; unsupported; approved alternative shown
Gemini Desktop:          installed; unsupported; approved alternative shown
Direct-provider control: routing only / observe / enforced
Dashboard:               http://127.0.0.1:<port>

The example does not prescribe machine state. It demonstrates that configured is not rendered as connected or protected now.

Command reference

Lifecycle

status.route_review prefers the gateway’s view of the release audit volume, then falls back to the local data directory for portable installs. It reports N requests this week to routes outside the admitted set only when readable history covers the full seven-day window. Retention loss, malformed records, missing numeric generations, shorter history, or the bounded scan limit changes that to an explicit At least N lower bound. No readable audit is unavailable, not zero.

Terms and licensing

Commercial-entitlement activation and deactivation remain future legal/product work. They have no CLI command in this build.

Providers and credentials

Clients and apps

smesh run first registers a bounded, payload-free session in the local gateway. If that handshake fails, it does not launch the command. The child receives process-local base URLs under /s/<opaque-id>/p/<alias>/; the gateway counts that session before request shedding, strips the session prefix, and then applies the ordinary pinned-alias, upgrade, representation, scanner, and policy pipeline. Skilak Mesh messages go to stderr so the child’s stdout remains pipe-safe. The foreground child’s exit or signal status remains the command’s exit status even when the final observation cannot be read.

The result has two independent grades:

• Path coverage says only that requests reached the sessionized mesh URL while this foreground command was active. They entered the ordinary mesh enforcement path and are subject to inspection or refusal. It does not prove which process made every request or that the tool had no other egress.
• Client coverage is an inventory claim about all known AI egress for that client. Claude Code CLI upgrades only after bounded executable-version evidence and with no Bedrock, Vertex, or Foundry selector active. Cursor is always incomplete because indexing and tab completion use Cursor’s backend. An unknown command receives no client-coverage upgrade.

An exact completed count of zero prints:

launched under smesh; no traffic observed; this tool may not honour base-URL variables.

This catches tools that scrub the environment, use a config file, hard-code an endpoint, or perform no model call during the launch. A gateway restart, lost finish response, or saturated counter is reported as unavailable/incomplete, never as zero. Per-session mode-0600 summaries contain only opaque IDs, timestamps, closed coverage grades, count/completeness, status, and exit code; they never contain argv, environment, working directory, credentials, prompts, command output, or provider responses. Exact in-memory observation requires the shipped single gateway worker. Detached descendants after the foreground command exits are outside that session and their session URL fails closed.

Policy and file handling

Enforcement

Dashboard, events, and logs

Operational logs and audit events are distinct: logs explain component health; events record payload-free enforcement metadata. Neither should contain query strings, provider credentials, matched secret values, or raw AI content.

Configuration, upgrades, and removal

Exit codes and automation

Stable exit codes should include: 0 success, 2 invalid usage, 10 terms or license action required, 20 unhealthy/fail-closed component, 21 policy invalid, 22 connector verification failed, 23 enforcement incomplete, 30 provider unavailable, and 40 upgrade/migration failed. JSON output must use stable schemas and never include secrets.

Automation must be explicit: no implicit terms acceptance, no provider call without --live, no privileged change under a generic --yes, and no fallback to direct provider access when the mesh is unavailable.

Shippable individual-beta scope

The smallest credible product is:

1. Homebrew install of smesh plus pinned/signed service images;
2. init, start, stop, status, doctor, and safe upgrades;
3. strict/balanced policy and text-only/file-deny selection;
4. secure provider setup through macOS Keychain;
5. reversible, tested Claude Code CLI and shared Codex configuration adapters;
6. operational logs, payload-free event summaries, and Dashboard Lite;
7. clear terms/license acceptance and individual/non-production usage mode; and
8. honest routing-only status with no claim that direct provider calls are blocked.

Direct-egress enforcement, additional client connectors, organization policy, and enterprise reporting can ship after this core. Security convergence on the the outstanding release blockers is a prerequisite for handling real sensitive data.

Source file: docs/SMESH-CLI-SPEC.md in SkilakLabs/mesh.