CLI command catalog
Generated builtin command contracts from Quirl; installed completion packs, plugins, and local discovery are excluded.
. <file> [args...]
Run a shell script and keep its variables
The POSIX spelling of source, with the same behavior.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
args— Theargsargumentfile— Thefileargument
bg [%job]
Resume a stopped job in the background
Sends SIGCONT to the selected process group without transferring terminal ownership.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
%job— The%jobargument
cd [path]
Change the shell working directory
Changes Quirl's process directory so later commands and prompt context follow it.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
path— Thepathargument
eval <code...>
Run shell setup code and keep its variables
Joins its arguments with spaces and runs them in the system POSIX shell, /bin/sh, as a foreground command. Afterwards the session adopts the exported environment and working directory the code ended with, so eval "$(ssh-agent -s)" and eval "$(brew shellenv)" work as in Bash or Zsh. Session variables are visible to the code. Variables it sets without export, functions, and aliases stay inside it.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
code— Thecodeargument
export NAME[=value]...
Set environment variables for later commands
export NAME=value sets and exports a variable. export NAME exports a variable an earlier bare NAME=value set, as setup code such as ssh-agent -s prints. A bare NAME=value sets a shell variable that later expansions see but child processes do not, and NAME=value command sets a variable for that one command.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
fg [%job]
Resume a job in the foreground
Transfers terminal ownership to the selected process group and waits until it exits or stops again.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
%job— The%jobargument
git commit [options]
Record changes to the repository
External command metadata demonstrates imported completion knowledge.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
-m,--message— Use the given commit message--amend— Replace the tip of the current branch--no-verify— Bypass pre-commit and commit-msg hooks-a,--all— Stage modified and deleted tracked files
git status [--short]
Show repository and working-tree status
External command metadata can eventually be imported from generated specs and help output.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
-s,--short— Use the compact status format
help [command or search text]
Explore commands and their contracts
Run quirl with no command to open a shell in your current terminal.
Type help to get started; exit or Ctrl-D returns to your previous shell.
Normal: run familiar commands and byte pipelines.
Data: type mode data for typed values; mode normal returns.
AI: type mode ai to plan with an authenticated Codex CLI. Proposals need review and never run automatically.
Tab completes; Ctrl-R searches history; Alt-Q opens modes and pickers. F1 explains the command at the cursor.
Use help <command> for examples, or help <words> to search the catalog.
Use help all to browse commands; refine a search when results are shortened.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
command— Thecommandargument
jobs
List structured background job state
Shows Quirl job ids, running/stopped/done state, and the original command. On Unix, direct human output escapes command controls; captured or file-redirected output retains raw source. Job text is constructed incrementally within 1 MiB; captured text also obeys a tighter request capture budget. Human stop notifications show at most 256 source bytes plus a truncation marker; typed job metadata stays complete.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
lua <expression>
Evaluate Lua without leaving command mode
Runs an expression in the persistent restricted Lua 5.5.1 VM.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
expression— Theexpressionargument
mode <normal|data|ai|toggle>
Switch the visible interactive grammar
Normal mode carries bytes and process status. Unquoted newlines separate commands; newlines after a pipe or boolean connector continue that command, and backslash-newline joins physical lines. Quoted newlines stay literal. Data mode evaluates Quirl's native structured values and pipelines. AI mode asks an installed Codex CLI for a typed proposal from a bounded compact view of the complete admitted catalog, then inserts the validated command for review without executing it. It has no local suggestion or planner fallback.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
normal|data|ai|toggle— One ofnormal,data,ai, ortoggle
quirl agent catalog [--format text|json]
Export installed commands and Lua host capabilities
Emits a versioned deny-unknown schema with deterministic catalog and HOST_API content hashes, provenance, installed capabilities, and their versions.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose accessible text or stable machine JSON
quirl agent context <query...> [--token-budget count] [--format markdown|json]
Build deterministic token-budgeted agent context
Ranks only installed command and HOST_API facts, selects the smallest relevant subtree within a documented deterministic token estimate, and records truncation and source hashes.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
query— Thequeryargument--format— Choose agent Markdown or stable machine JSON--token-budget— Bound the canonical context payload
quirl agent manifest [--format text|json]
Export installed tools, versions, schemas, and validators
Lists only tools and capabilities installed in this Quirl composition, with schema/content hashes and validation commands grounded in the semantic catalog and generated Lua HOST_API.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose accessible text or stable machine JSON
quirl agent validate <file> --kind catalog|context|manifest [--format text|json]
Validate a versioned agent contract without execution
Reads at most 4 MiB from an admitted regular file, then rejects unknown fields, unsupported schema versions, tampered content hashes, nondeterministic ordering, and context payloads that exceed their declared token budget.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file— Thefileargument--format— Choose accessible diagnostics or stable JSON--kind— Select the deny-unknown document schema
quirl ai index [--format text|json]
Build local semantic command and option embeddings
Loads the pinned Quirl command model from local files, embeds bounded command and option documents, validates every vector, and atomically replaces the SQLite database only after a complete transaction.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose accessible text or stable machine JSON
quirl ai related <command...> [--limit count] [--format text|json]
Suggest related commands and options
Uses the same local semantic index as AI mode, excludes the requested command, and returns bounded suggestions without execution.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
command— Thecommandargument--format— Choose accessible text or stable machine JSON--limit— Bound returned suggestions to at most 100
quirl ai run <query...>
Preview and explicitly confirm one catalog-backed command
Sends the bounded natural-language intent and a compact projection of the complete admitted command catalog to one installed, authenticated Codex CLI process. Codex runs ephemerally with user configuration, rules, and agent tools disabled, and may return only a schema-constrained command ID plus typed catalog arguments. There is no local-planner fallback. Quirl asks for unresolved required values, revalidates against the current complete catalog, renders the exact quoted command, and requires explicit acceptance before execution. Unknown effects, filesystem mutation, process spawning, and session changes show their reason and require a distinct second high-risk confirmation.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
query— Thequeryargument
quirl ai search <query...> [--limit count] [--kind all|command|option] [--format text|json]
Find commands and options by task intent
Always ranks the complete bounded lexical document set and fuses it with matching local Model2Vec embeddings when the exact model, document-generation version, dimensions, and index fingerprint agree. Missing, stale, cancelled, invalid, or mismatched semantic state falls back to lexical results. Search is local, CPU-only, network-free, and never executes a result.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
query— Thequeryargument--format— Choose accessible text or stable machine JSON--kind— Restrict results to commands, options, or both--limit— Bound returned suggestions to at most 100
quirl ai status [--format text|json]
Inspect local command-intelligence readiness
Reports the SQLite command database, local model manifest, and complete stored embedding-index identity—including hashes, dimensions, document-generation version, and index fingerprint—without contacting the network.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose accessible text or stable machine JSON
quirl assets retry [--manifest path] [--format text|json]
Explicitly retry deferred runtime assets
Clears bounded backoff and permanent-failure state, then performs the same verified update transaction. Core shell operation remains available if the retry fails.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose accessible text or stable machine JSON--manifest— Use a local manifest for offline or mirror-managed installation
quirl assets status [--format text|json]
Inspect separately downloaded runtime assets
Validates installed completion-database and command-model receipts, payloads, and per-asset source identities without network access, and reports degraded operation plus bounded retry state.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose accessible text or stable machine JSON
quirl assets update [--manifest path] [--format text|json]
Install compatible runtime assets from a verified manifest
Reads this Quirl version's deny-unknown website channel manifest, downloads independently refreshed content-addressed payloads over bounded HTTPS without a shell, verifies exact binary compatibility, per-asset provenance and license notices, format, byte size, and SHA-256, then atomically switches the current receipt while preserving the prior valid generation.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose accessible text or stable machine JSON--manifest— Use a local manifest for offline or mirror-managed installation
quirl catalog [--format text|json|markdown]
Export installed command knowledge for humans or AI
Emits the versioned semantic catalog bundled with this binary.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose a stable output format
quirl check <file|directory> [--format text|json]
Validate scripts without executing them
Deterministically discovers Lua and Quirl scripts through a bounded, non-recursive traversal that skips links and build/VCS directories; checks Lua syntax, annotations, modules, and restricted APIs plus Quirl statement structure; and aggregates structured diagnostics without executing source.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file|directory— One offileordirectory--format— Choose diagnostic output
quirl complete <input> [--format text|json]
Query the semantic completion engine
Returns the same attributed completion items used by the interactive editor.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
input— Theinputargument--format— Choose stable text or JSON output
quirl config check <file> [--format text|json]
Validate Lua configuration through Rust schemas
Evaluates under config restrictions, validates the returned Lua graph before allocating typed configuration, and preserves the active last-known-good value on failure. Returns are bounded to 256 KiB of retained strings, 4112 key/value nodes, and nesting depth 16; cyclic or repeated tables are rejected.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file— Thefileargument--format— Choose output format
quirl config diff <file> <other> [--format text|json]
Compare two evaluated configurations
Loads both authoritative Lua files under the restricted schema policy and reports deterministic field-level differences without changing either file.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file— Thefileargumentother— Theotherargument--format— Choose output format
quirl config doctor <file> [--format text|json]
Diagnose configuration schema and editability
Validates the authoritative configuration and reports which recognized settings are safe literal patches versus code-controlled expressions; it never writes source.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file— Thefileargument--format— Choose output format
quirl config export <file> [--format text|json]
Export evaluated schema-backed configuration
Reads and validates config.lua, then emits a deterministic terminal-safe text view or versioned JSON document without modifying source.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file— Thefileargument--format— Choose output format
quirl config fmt <file> [--check]
Format a Lua configuration deterministically
Validates the authoritative configuration, then applies Quirl's deterministic Lua formatter. --check reports drift and never writes.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file— Thefileargument--check— Report formatting drift without writing
quirl config get <file> <key>
Read one evaluated configuration value
Evaluates the complete restricted Lua configuration, validates it through Rust schemas, and prints one recognized typed field.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file— Thefileargumentkey— Thekeyargument
quirl config migrate <file> --dry-run [--format text|json]
Preview a schema migration without rewriting configuration
Previews migration of an unversioned or explicit v1/v2/v3 configuration to the current v4 schema. --dry-run is required; the candidate source is reported without writing the source or a backup file.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file— Thefileargument--format— Choose output format--dry-run— Require a non-mutating migration preview
quirl config set <file> <key> <value>
Safely patch one literal configuration value
Changes only a recognized literal field in quirl.config, including prompt.symbols (auto, plain, unicode, or explicit nerd_font), validates the complete candidate before an atomic replacement, and retains the previous source as .bak.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file— Thefileargumentkey— Thekeyargumentvalue— Thevalueargument
quirl config tui <file>
Inspect schema-backed configuration in the terminal
Shows current editor, picker, and prompt symbol values, allowed values, and textual editing guidance in an accessible line-oriented view.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file— Thefileargument
quirl config web [file] [--port <port>]
Open the local schema-backed configuration form
Serves an accessible configuration form only on IPv4 loopback. The private session URL carries a CSRF token; saves validate the complete Lua configuration, retain a .bak, preserve non-overlapping concurrent source edits, and reject conflicting or code-controlled fields. Omitting file defaults to the discovered config.lua (QUIRL_CONFIG_DIR, XDG_CONFIG_HOME, or ~/.config/quirl).
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file— Thefileargumentport— Theportargument--port— Loopback port; 0 selects an available port
quirl data <source> [| transform ...] [--format table|plain|json]
Evaluate a native structured-data pipeline
Sources are pwd, files [path] (or ls), open <path>, JSON, or explicit ^external <command>. Values stay typed through streams and transforms: filesystem rows retain Path, Size, and DateTime; tar retains Path and Size; TOML retains DateTime. JSON/YAML/TOML and bytes are explicit conversion boundaries, and to json documents its lossy domain encoding. The CLI injects a deadline-, cancellation-, and output-bounded external host; library runtimes fail closed without one. CSV/tar rows are pulled lazily and all adapters enforce byte, row, field, depth, node, retained-text, and materialization limits. sort, table output, envelopes, and collected convenience APIs intentionally materialize within those limits. Transforms include typed where comparisons with and/or and size literals such as 10kB, dotted get, select, reject, sort-by <field> [-r] (or sort), first [n], last [n], take, skip, reverse, uniq, group-by, columns, exact math sum|min|max|avg, and length; first and last without a count produce an Option. Numeric predicates and sorting compare retained decimal text exactly against signed and unsigned integers, without binary-float rounding; decimal exponents must fit a signed 64-bit integer. CSV columns remain strings: compare a boolean-looking cell with where enabled == "true", without implicit type inference. select requires every requested field in each consumed row and preserves requested field order; a missing field reports the transform location and available fields. Task remains declarative state; HTTP is not an implicit source.
- Input:
Nothing - Output:
Value - Live streaming:
true
Options:
source— Thesourceargument--format— Choose a human table/plain renderer or the stable typed JSON envelope
quirl data ls [path]
List a directory as typed entries in Data mode
ls is a Data-mode source alias for files. It produces typed filesystem entries for structured transforms. Normal mode does not use this contract: an unqualified ls there resolves through PATH and uses the installed system command's contract.
- Input:
Nothing - Output:
Stream<Entry> - Live streaming:
true
Options:
path— Thepathargument
quirl describe <command> [--format text|json|markdown|html]
Describe one installed command
Renders one exact entry from the same semantic catalog used by completion, documentation, language services, and agents.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
command— Thecommandargument--format— Choose a deterministic documentation view
quirl doc [--format text|json|markdown|html] [--output path] [--open]
Generate installed command documentation
Generates deterministic human or machine documentation from the installed catalog, writes requested files atomically, and can open an explicit output in the platform viewer.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose a deterministic documentation view--output— Atomically write the generated view--open— Open the explicit output in the default viewer
quirl eval <lua-expression>
Evaluate Lua and print the returned value
Runs one expression in the same restricted, budgeted Lua runtime used by scripts.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
lua-expression— Thelua-expressionargument
quirl events schema [--format text|json]
Describe the installed typed extension protocol
Lists immutable lifecycle, directory, plan, progress, output, cancellation, result, and error events together with declared mutation capabilities and the composed catalog, completion, and panel contribution kinds.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose accessible text or versioned machine JSON
quirl events validate <file> [--format text|json]
Validate an immutable extension event trace
Reads at most 4 MiB from an admitted regular file, then checks the deny-unknown versioned envelope, protocol version, safe output text, and strictly increasing event sequence without invoking a plugin.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file— Thefileargument--format— Choose accessible text or stable validation JSON
quirl exec <source> [--format text|json]
Execute Quirl's native command graph
Accepts complete Quirl source as exactly one outer-shell argument and passes it unchanged to extension planning. Without an explicit extension rewrite, the same source is parsed, diagnosed, and captured for bounded, redacted recovery. Unquoted newlines separate commands; newlines after |, &&, or || continue the command, and backslash-newline joins physical lines. Quoted newlines remain literal. Quoting, empty arguments, byte pipes, redirects, boolean lists, and background jobs must be written inside that source operand; additional argv elements are rejected rather than joined into executable syntax.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
source— Thesourceargument--format— Choose human-readable or stable ShellError output for failures
quirl fmt <file|directory> [--check]
Format Lua and Quirl scripts deterministically
Deterministically discovers Lua and native .qrl scripts (including .quirl and .🌀 aliases), formats them through their bounded formatters, and installs changed source through a synchronized same-directory atomic replacement that rejects links, aliases, special files, and observed concurrent changes. --check never writes.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file|directory— One offileordirectory--check— Report drift without writing
quirl index build [--fish path]... [--bash path]... [--zsh path]... [--help path]... [--man path]... [--output path] [--format text|json]
Build the attributed completion index
Imports declarative Fish, Bash, and Zsh completions from admitted regular files up to 4 MiB each, retaining at most 256 commands per declaration, 2,048 commands, 4,096 candidates, and 4 MiB of normalized catalog text per file. Help/man text is limited to 1 MiB each. It never sources or executes providers, commands, or man, then atomically writes a versioned catalog.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--bash— Import a Bash completion file or directory--fish— Import a Fish completion file or directory--format— Choose the build report format--help— Parse supplied command-help text without executing its command--man— Parse supplied rendered/raw man text without invoking man--output— Write a specific index instead of the default cache--zsh— Import a Zsh completion file or directory
quirl index explain <command...> [--index path] [--format text|json]
Explain where indexed command facts came from
Reads an admitted regular catalog file up to 4 MiB, then shows source kind, confidence, origin, and fingerprint for command metadata and each retained option.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
command— Thecommandargument--format— Choose the explanation format--index— Read a specific catalog index
quirl lint <file|directory> [--format text|json]
Lint scripts without executing them
Aggregates annotation and capability diagnostics for scripts found through the same bounded non-recursive discovery contract and rejects ambient APIs that bypass Quirl capabilities.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file|directory— One offileordirectory--format— Choose diagnostic output
quirl lsp
Serve generated Lua and native Quirl (.qrl) editor intelligence
Speaks a deterministic LSP subset over stdio, using the generated Lua HOST_API and semantic command catalog for diagnostics, completion, hover, signatures, and module docs without evaluating documents. Full-document changes require increasing integer versions and reject incremental ranges without replacing retained text.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
quirl new <name> [--lang lua|quirl] [--directory path]
Create a checked script
Writes a deterministic Lua or native Quirl script with create-new semantics, so an existing script is never overwritten. Lua is the default; --lang quirl generates the canonical .qrl extension. .quirl and .🌀 remain accepted input aliases.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
name— Thenameargument--directory— Choose the destination directory--lang— Choose Lua (the default) or native Quirl (.qrl)
quirl package build [--manifest path] [--format text|json]
Validate and build a deterministic package contract
Checks the entry path, Quirl version range, installed capabilities, and the public-command quality gate for summaries, argument docs and types, examples, effects, and error codes; it returns content hashes without executing Lua.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose accessible diagnostics or stable JSON--manifest— Build a manifest other than ./plugin.toml
quirl package manifest [--manifest path] [--format text|json]
Parse a versioned project package manifest
Reads a deny-unknown plugin.toml schema and shows normalized package identity, Quirl compatibility, requested capabilities, and contributions without loading its Lua entry.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose accessible text or stable machine JSON--manifest— Read a manifest other than ./plugin.toml
quirl package publish --dry-run [--manifest path] [--format text|json]
Preview a deterministic network-free package publication
Runs the complete package build quality gate and emits the files, build hash, and requested permissions that would be published. Phase 2 performs no network publication.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose accessible text or stable JSON--manifest— Read a manifest other than ./plugin.toml--dry-run— Require a network-free publication plan
quirl pick [--source stdin|history|files|actions|projects] [--query text] [--multi] [--limit count] [--root path] [--refresh] [--format text|json]
Select typed values with Quirl's shared fuzzy engine
The same deterministic exact/fuzzy/inverse query model ranks history, files, cached Git projects, actions, jobs, completions, and data while returning the original value. Cached projects prefer the newest bounded Git-metadata activity or Quirl open; an explicit refresh evaluates the active project roots and exclusions before scanning.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose stable output--limit— Bound multi-selection output--query— Set the initial fuzzy query--root— Set the file provider root--source— Choose the typed provider--multi— Return multiple selected values--refresh— Refresh projects using the active config before selection
quirl plugin add <source> [--allow capability]... [--format text|json]
Install a local plugin with explicit permission approval
Reads the manifest and entry only from admitted regular files under their 256 KiB and 4 MiB limits. It validates the versioned runtime boundary, shows the permission diff, records SHA-256 source checksums, and atomically installs a disabled permission lock without implicit network access. Plugin mutations serialize across processes; lock writes are capped at 4 MiB and stop when preserved transaction files need review.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
source— Thesourceargument--allow— Approve one requested capability after review; repeat as needed--format— Choose accessible text or stable machine JSON
quirl plugin check <file> [--format text|json]
Validate Lua plugin registrations
Reads at most 4 MiB from an admitted regular file, then loads a trusted plugin with process access denied and validates prompt and completion callbacks.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file— Thefileargument--format— Choose output format
quirl plugin disable <name> [--format text|json]
Disable a plugin while retaining its permission lock
Atomically changes only enabled state; source, checksums, versions, and granted capabilities remain locked for inspection and recovery. Plugin mutations serialize across processes; lock writes are capped at 4 MiB and stop when preserved transaction files need review.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
name— Thenameargument--format— Choose accessible text or stable machine JSON
quirl plugin doctor <name> [--format text|json]
Diagnose plugin schema, source integrity, permissions, and runtime boundaries
Verifies lock schema/API versions and SHA-256 checksums, then validates trusted Lua registrations or isolated Wasm/out-of-process boundaries with accessible diagnostics.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
name— Thenameargument--format— Choose accessible text or stable machine JSON
quirl plugin enable <name> [--format text|json]
Enable a checksum-verified installed plugin
Runs doctor and the declared non-executing or budgeted trusted boundary before atomically enabling the existing locked plugin. Plugin mutations serialize across processes; lock writes are capped at 4 MiB and stop when preserved transaction files need review.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
name— Thenameargument--format— Choose accessible text or stable machine JSON
quirl plugin permissions <name> [--format text|json]
Inspect requested and granted plugin authority
Reads the permission lock and emits requested, granted, added, removed, and unchanged capabilities without loading plugin code.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
name— Thenameargument--format— Choose accessible text or stable machine JSON
quirl plugin remove <name> [--format text|json]
Remove an installed plugin lock without deleting source
Atomically removes the named permission record; external source directories are never deleted by the plugin manager. Plugin mutations serialize across processes; lock writes are capped at 4 MiB and stop when preserved transaction files need review.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
name— Thenameargument--format— Choose accessible text or stable machine JSON
quirl plugin update --locked [--format text|json]
Verify installed plugins without changing locked authority
Re-resolves every local source and rejects any version, checksum, API, or permission change; platform v0.1 does not perform network updates. Plugin mutations serialize across processes; lock writes are capped at 4 MiB and stop when preserved transaction files need review.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose accessible text or stable machine JSON--locked— Forbid changes to versions, checksums, API versions, and capabilities
quirl projects clone <repository> [--root path]
Clone a Git project into a GHQ-compatible directory
Clones an HTTP(S), SSH, or scp-style repository into <root>/<host>/<repository-path>, preserving nested namespaces and removing the final .git suffix. Resolves the root from --root, GHQ_ROOT, Git's ghq.root configuration, then ~/Projects. With multiple ghq.root values, reuses a matching checkout in any configured root or creates a new checkout under the first root. Uses Git's normal authentication and foreground terminal behavior. An existing checkout is reused only when its origin matches; conflicting destinations are errors, and reuse never pulls or overwrites files. Successful checkouts become available to the project picker. Nondefault ports use a host__port_NNN directory component. SSH host aliases are preserved without resolving SSH configuration. Embedded HTTP credentials, encoded paths, IPv6 literals, local paths, and unsupported transports require ordinary git clone with an explicit destination; use Git's credential helper for managed HTTP authentication.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
repository— Therepositoryargument--root— Override the parent directory for this managed clone
quirl projects policy [ask|managed|off]
Inspect or set interactive managed-clone suggestions
Without an argument, prints the saved policy; missing state defaults to ask. ask enables a one-time offer for a standalone literal git clone URL in rich Normal mode. managed explicitly opts in to the managed location for future eligible clones. off disables offers and automatic destination changes. Options, explicit destinations, expansions, compound commands, and scripts are always unchanged. Choosing the original command, using a managed location once, or dismissing suggestions saves off; cancelling keeps ask. Explicit quirl projects clone remains available under every policy. Stores a strict, versioned preference atomically in the XDG state directory, separately from Lua configuration.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
ask|managed|off— One ofask,managed, oroff
quirl projects root [--root path]
Print the effective parent directory for managed Git projects
Resolves and prints the managed-clone root without creating directories, cloning a repository, or changing the shell's working directory. Resolution prefers --root, then GHQ_ROOT, Git's ghq.root configuration, then ~/Projects. With multiple ghq.root values, prints the first root used for new clones. The root holds separate Git checkouts in <host>/<repository-path> subdirectories; GHQ itself is not required.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--root— Override the root used for this resolution
quirl recover <list|show> [--format text|json]
Inspect recoverable command-failure snapshots
Lists or displays versioned atomic snapshots containing a redacted command, working directory, environment diff, bounded captured output, timing, status, and error chain.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
list|show— One oflistorshow--format— Choose stable text or JSON output
quirl recover list [--format text|json]
List recoverable command-failure snapshots
Lists versioned snapshot identifiers newest first without reading or replaying command contents.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose stable text or JSON output
quirl recover show [id] [--format text|json]
Inspect one recoverable command-failure snapshot
Displays an explicit snapshot or the newest available snapshot, including redacted context and bounded captured output; it never replays the command.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
id— Theidargument--format— Choose stable text or JSON output
quirl run <file|-> [--lang lua|quirl|bash|zsh] [arguments...]
Run a script through its explicit language engine
Reads at most 4 MiB from an admitted regular file, or bounded standard input. Selects a language by explicit flag, shebang, or extension; Lua uses the restricted VM, .qrl uses native executors, and .quirl plus .🌀 are accepted native aliases. Bash/Zsh use reference interpreters with startup files disabled and structured capture.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
arguments— Theargumentsargumentfile|-— One offileor---lang— Select the language explicitly, including for stdin
quirl sdk [--format text|json|markdown]
Export the generated Lua extension SDK
LuaLS stubs, AI JSON, and human documentation are generated from the same Rust host API definitions.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose the generated SDK view
quirl serve mcp --capabilities catalog|complete|check|format
Serve explicitly granted source intelligence over MCP stdio
Supports modern 2026-07-28 discovery and explicitly negotiated legacy clients. Each process exposes only the requested bounded catalog, completion, source-check, and source-format tools; it grants no filesystem, network, plugin, or command-execution authority. Admission limits messages to 1 MiB, methods to 128 bytes, encoded parameters to 256 KiB, and JSON nesting to 32 containers before dispatch.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--capabilities— Grant one or more comma-separated MCP tools
quirl test [file|directory]
Run a Lua test module under resource limits
Discovers conventional Lua test modules through the bounded non-recursive authoring traversal and runs every returned test_* function in an isolated restricted runtime.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
file|directory— One offileordirectory
quirl view directory [path] [--all] [--format text|json]
Render a directory as an escape-safe typed panel
Produces a line-oriented name, kind, byte-size, and modification view with a plain fallback; raw terminal control bytes are rejected.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
path— Thepathargument--format— Choose the plain view or typed panel model--all— Include hidden entries
quirl view panel <name> [--format text|json]
Render an enabled plugin's typed panel contribution
Invokes one permission-locked, deadline-bounded panel provider, validates its escape-free PanelModel and declared plain fallback, then renders accessible text or JSON.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
name— Thenameargument--format— Choose the plain view or typed panel model
quirl view processes [--format text|json]
Render the process table as an escape-safe typed panel
Reads the platform process table into typed pid, parent, state, and command cells and renders an accessible plain fallback without accepting terminal escapes.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
--format— Choose the plain view or typed panel model
quirl watch <expression> [--samples count] [--interval-ms ms] [--capacity count] [--format text|json]
Watch a typed data pipeline with bounded live samples
Re-evaluates the native data expression until the declared sample bound or Ctrl-C, checks cancellation between stages and during refresh waits, retains a bounded completed-sample history, and reports older samples dropped from retention.
- Input:
Nothing - Output:
Stream<Value> - Live streaming:
true
Options:
expression— Theexpressionargument--capacity— Bound retained samples to at most 256--format— Choose live lines or a bounded JSON snapshot--interval-ms— Set the cancellable refresh interval--samples— Set a bounded sample count
source <file> [args...]
Run a shell script and keep its variables
Runs the file in the system POSIX shell, /bin/sh, with any arguments as its positional parameters. Afterwards the session adopts the exported environment and working directory the script ended with, so source .venv/bin/activate or source .env work. A name without a slash refers to the file in the current directory when one exists. Variables set without export, functions such as a virtual environment's deactivate, and aliases stay inside the script.
- Input:
Nothing - Output:
Bytes - Live streaming:
false
Options:
args— Theargsargumentfile— Thefileargument
unset NAME...
Remove shell and environment variables
Removes each named variable from the session, whether exported or not. Names that are not set are ignored. Quirl has no shell functions, so unset -f is rejected.
- Input:
Nothing - Output:
Bytes - Live streaming:
false