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 API keys. Only providers with API keys in the environment are queried.

  • lectic script Run an ES module file using Lectic’s internal Bun JS runtime. Works as a hashbang interpreter, useful for writing subcommands (see below), hooks, and exec tools. For example:

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

Custom Subcommands

Lectic supports git-style custom subcommands. If you invoke lectic <command>, Lectic will look for an executable named lectic-<command> in your configuration directory, data directory, or PATH.

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 <PATH> Read from the given file and update it in place. Mutually exclusive with --file.

  • -s, --short Only emit the newly generated assistant message, not the full updated conversation.

  • -S, --Short Like --short, but emits only the raw message text (without the :::Speaker wrapper).

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

  • -q, --quiet Suppress printing the assistant’s response to stdout.

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

Constraints

  • –inplace cannot be combined with –file.
  • –quiet cannot be combined with –short or –Short.

Common examples

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

    lectic -i conversation.lec

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

    cat conversation.lec | lectic

  • Stream just the new assistant message:

    lectic -s -f conversation.lec

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

    echo "This is a new message." | lectic -i 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