Reference: Command‑Line Interface

The lectic command is the primary way to interact with Lectic. It can read from a file or from standard input, and it offers flags to control how the result is printed or saved.

Usage

lectic [FLAGS] [OPTIONS] [SUBCOMMAND] [ARGS...]

Subcommands

• lectic lsp Start the LSP server. Transport: stdio.

• lectic parse Parse a lectic file into a JSON representation of the parsed file structure. Useful for programmatic analysis and modification.

  Flags:

  • --yaml: Emit YAML instead of JSON.
  • --reverse: Ingest JSON (or YAML) output and reconstruct the original lectic file.

• lectic models List available models for providers with detected credentials.

  Providers with API keys in the environment are queried. The codex provider is listed if you have previously logged in (it is not an API key-based provider).

• lectic script Bundle and run a JS/TS/JSX/TSX module using Lectic’s internal Bun runtime. Works as a hashbang interpreter, useful for writing subcommands (see below), hooks, and exec tools.

  During bundling, Lectic supports explicit remote imports via https://... URLs (and http:// for localhost only), in order to easily support writing self-contained single-file scripts.

  For TSX/JSX scripts using React’s automatic runtime, include an explicit import React from "https://..." so Lectic can resolve the implicit react/jsx-runtime / react/jsx-dev-runtime imports.

  Bundled output is cached on disk under $LECTIC_CACHE/scripts/. The cache key includes the script contents, the Bun version, and an internal plugin version. Delete that directory to force a re-bundle.

  Note: remote imports are treated as pinned by URL. Changes on the remote server will not invalidate the cache automatically.

  Prefer versioned URLs so builds are reproducible. For example, when using esm.sh, import react@18.3.1 instead of react:

  import React from "https://esm.sh/react@18.3.1"

  For example:

  #!/bin/env -S lectic script
  console.log("Hello from a lectic script!")

• lectic a2a Start an A2A (JSON-RPC + SSE) server exposing configured agents.

  Options:

  • --root <path>: Workspace root (process.chdir to this path).
  • --host <host>: Bind host. Default: 127.0.0.1.
  • --port <port>: Bind port. Default: 41240.
  • --token <token>: If set, require Authorization: Bearer <token>.
  • --max-tasks-per-context <n>: Maximum number of task snapshots to keep in memory per contextId. Default: 50.

  Monitoring endpoints (HTTP):

  Cross-agent:

  • GET /monitor/agents
    • Lists configured agents.
  • GET /monitor/tasks
    • Returns recent task snapshots across all agents.
    • Optional query: ?agentId=<id>&contextId=<id>.
  • GET /monitor/tasks/<taskId>
    • Returns a single task snapshot, searching across all agents.
  • GET /monitor/events
    • Server-Sent Events stream of task lifecycle events.
    • Optional query: ?agentId=<id>&contextId=<id>.

  Per-agent:

  • GET /monitor/agents/<id>/tasks
    • Returns recent task snapshots.
    • Optional query: ?contextId=<id>.
  • GET /monitor/agents/<id>/tasks/<taskId>
    • Returns a single task snapshot.
  • GET /monitor/agents/<id>/events
    • Server-Sent Events stream of task lifecycle events.
    • Optional query: ?contextId=<id>.

  If --token is set, the monitoring endpoints require Authorization: Bearer <token>.

Custom Subcommands

Lectic supports git-style custom subcommands. If you invoke lectic <command>, Lectic looks for an executable named lectic-<command> in this order by default:

1. $LECTIC_CONFIG (searched recursively)
2. $LECTIC_DATA (searched recursively)
3. $PATH entries (top-level per entry)

If LECTIC_RUNTIME is set, Lectic searches those PATH-style directories first for recursive discovery, then continues with $LECTIC_CONFIG and $LECTIC_DATA.

See Custom Subcommands for a full guide on creating subcommands and adding tab completion for them.

Bash completion

The repository includes a bash completion script. See Getting Started for installation instructions.

The completion system is extensible. You can write plugins to provide completions for your custom subcommands. See the Custom Subcommands guide for details.

Flags and options

• -v, --version Prints the version string.

• -f, --file <PATH> Path to the conversation file (.lec) to process. If omitted, Lectic reads from standard input.

• -i, --inplace Update the file in place. Requires --file.

• --format <mode> Controls output shape and visibility. Supported modes:

  • full: print full updated conversation (default)
  • block: print only the new :::Speaker ... ::: block
  • raw: print only the new assistant message content
  • clean: stream only assistant text, stripping tool calls, thought blocks, and inline attachments
  • none: print nothing

• -s, --short (deprecated) Alias for --format block.

• -S, --Short (deprecated) Alias for --format raw.

• -l, --log <PATH> Write detailed debug logs to the given file.

• -q, --quiet (deprecated) Alias for --format none.

• -h, --help Show help for all flags and options.

Constraints

• –inplace requires –file.
• –format cannot be combined with legacy output flags: –short, –Short, or –quiet.

Common examples

• Generate the next message in a file and update it in place:

  lectic -if conversation.lec

• Read from stdin and write the full result to stdout:

  cat conversation.lec | lectic

• Stream just the new assistant block:

  lectic --format block -f conversation.lec

• Add a message from the command line and update the file:

  echo "This is a new message." | lectic -if conversation.lec

• Stream user-facing text only (hide tools and thoughts):

  lectic --format clean -f conversation.lec

• List available models for detected providers:

  lectic models

• Start the LSP server (stdio transport):

  lectic lsp

• Parse a file to JSON:

  lectic parse -f conversation.lec

• Round-trip a file through parsing and reconstruction:

  lectic parse -f conversation.lec | lectic parse --reverse