nerima-lisp/paredit-cli

paredit-cli

paredit is a structure-aware CLI for inspecting and safely refactoring Lisp S-expressions, designed for both people and AI coding agents. It supports Common Lisp, Emacs Lisp, LFE, Scheme, Racket, Clojure, Hy, Carp, Janet, and Fennel.

Full documentation — command reference, safe editing workflows, the agent interface, and integration guides — is published at <https://nerima-lisp.github.io/paredit-cli/. The source for that site lives in docs/src/.

Commands

paredit inspect <report> [args]    # read-only inventory, validation, analysis
paredit edit <transform> [args]    # one structural edit (stdout, --diff, or --write)
paredit refactor <workflow> [args] # plan, preview, verify, and apply changes
paredit config <command>           # inspect and validate the layered paredit.toml
paredit generate <generator> [args] # generate new source: defpackage, defsystem, tests, ...
paredit lsp                        # Language Server Protocol server over stdio
paredit mcp                        # Model Context Protocol server over stdio (agents)
paredit serve                      # resident analysis server over HTTP/JSON-RPC
paredit tui <file>                 # interactively browse a file's tree; prints --path on exit
paredit completions <shell>        # shell completion scripts (bash/zsh/fish/...)

Run paredit --help, then paredit <namespace --help for the complete command list. For machine-readable discovery, run paredit inspect capabilities --output json.

Quick Start

paredit inspect check --file src/example.lisp
paredit edit wrap --file src/example.lisp --path 0.2 --diff
paredit refactor plan --symbol old-name src/example.lisp

# Name a form without counting parentheses: by definition name, by editor
# coordinate, or by shape. `inspect resolve` shows what a selector matches.
paredit inspect resolve --file src/example.lisp --query '(defun ?name ...)'
paredit edit wrap --file src/example.lisp --name parse-header --diff

Install

nix run github:nerima-lisp/paredit-cli -- --help    # run without installing
nix profile install github:nerima-lisp/paredit-cli # install via Nix
cargo install --git https://github.com/nerima-lisp/paredit-cli --locked
nix develop -c cargo install --path . --locked   # from a local checkout

The current minimum supported Rust version is 1.85. See the installation guide for the Cachix binary cache, flake overlay, and commit-pinning for automation.

Stability

paredit-cli follows Semantic Versioning. From 1.0.0 onward, command paths, flags, exit codes, documented JSON fields, the pareditcli crate-root API, and the Nix outputs are stable within the 1.x series; human-readable text output is not a machine contract. The compatibility guide lists exactly what an upgrade may and may not change.

Development

nix develop
cargo test
nix flake check

Pull requests run every nix flake check output, one CI job per check, so the gate costs the slowest check rather than the sum of all of them. A typed Rust library API behind the CLI is documented in src/lib.rs; build it locally with cargo doc --no-deps --open. The rendered command reference and guides live at the documentation site.

Community and security

• Contributing
• Code of Conduct
• Support
• Security
• Releasing