Single prompts and streams
Prerequisites: existing authentication, a deliberately trusted project and reviewed settings/hooks/MCP sources. Single prompts are not interactive chat dialogs. These commands send model requests and may incur costs.
lurus chat --mode ask --prompt "Explain the architecture without edits" --output-format text
lurus chat --mode ask --prompt "Summarize the architecture" --output-format stream-json
--prompt or a prompt supplied as positional arguments starts single-prompt mode. The session is saved; a successful run exits with code 0 and a failed run with code 1. Without interactive input, actions requiring consent for secrets, dangerous operations or protected settings are rejected. Other actions may be approved once. This does not provide comprehensive read-only protection. Ask mode also restricts ordinary edits, but does not prevent every process action.
--max-turns 12 limits main-agent model requests including retries. Supply a positive safe integer in decimal digits, without a sign, decimal places or whitespace. It requires a single prompt, not interactive chat or --pipe; invalid combinations exit with code 1 before authentication. This is separate from custom-agent maxTurns and is not a cost cap.
text outputs text. json and stream-json currently use the same NDJSON event stream, not a single final JSON object. Parse each line separately: system/init, assistant/text, tool_use_begin/tool_input/tool_use_end, system/turn_complete/error/done and other runtime events. Reassemble text chunks and check errors/process status.
For machine-readable output, use --output-format json or --output-format stream-json with a space before the value. Only these forms activate the appropriate log redirection, not -o json, --output-format=json or --output-format=stream-json. stdout carries data and stderr carries diagnostics. Do not parse log lines as JSON.
JSON schema: instruction, not validator
Complete summary.schema.json:
{
"type": "object",
"properties": { "summary": { "type": "string" } },
"required": ["summary"],
"additionalProperties": false
}
lurus chat --mode ask --prompt "Summarize the project" --json-schema summary.schema.json --output-format json
The CLI reads the schema and adds a JSON instruction to the prompt. The response is not automatically validated against the schema. If the file cannot be read, the CLI warns and continues without that instruction. Exit code 0 therefore guarantees neither a valid JSON response nor schema compliance. The outer output remains NDJSON. Reconstruct the response text in the consuming system, parse the JSON and check it with a suitable validator.
Batch file
Warning: Batch runs can modify files and execute processes. Asking for “without changing files” in a prompt does not enforce read-only access. Use trusted inputs and narrowly scoped tasks.
Save the following prompt blocks as prompts.txt. A separate line containing --- divides the blocks:
Explain the architecture without changing files.
Include the key module boundaries.
---
Summarize existing tests without changing files.
lurus batch prompts.txt --output-format json --continue-on-error
A prompt can span several lines. Conversation history is cleared between prompts. Use the optional --model <selection> flag to choose a model. Output defaults to text; JSON is also supported. Without --continue-on-error, the run stops at the first failure. --max-turns 12 limits main-agent model requests, including retries, separately per prompt, using the same integer rules as above. A run with failures exits with code 1 even if it continues. An empty prompt list exits with code 0.
The JSON output contains file, totalPrompts, processed, succeeded, failed, totalTokens and results. Each result contains prompt, status, response, attachmentNotices and tokens. Check the actual responses and notices, not just the number of successful prompts.
Pipe and PR context
lurus chat --pipe
The pipe is an advanced, long-lived integration over stdin and stdout that requires authentication. The ready event may arrive before initialization is complete. Clients must process consent and subsequent events rather than assume immediate readiness. Starting a new pipe session can save explicitly supplied model, thinkingMode, effort, maxMode and mode values globally, affecting later sessions. Resuming existing sessions does not save these values in the same way.
--from-pr <number> first attempts the local comparison git diff origin/main...HEAD. Only if that fails does it use gh pr diff <number>. Context is limited to 50,000 characters. This does not guarantee that the specified pull request is loaded every time. Check the Git comparison base and authentication for gh first.
Safe environment and troubleshooting
Obtain LURUS_API_KEY from a secret manager or protected CI variable. Never put real keys in examples or shell history. A nonempty environment variable overrides stored credentials; an invalid value does not fall back to the stored login. LURUS_AUTO_CONSENT grants broad consent for settings, hooks and MCP and is not a recommended default. Child processes receive only allowlisted environment variables. Extra names in *_PASS_ENV are deliberate trust grants.
For a broken JSON pipeline, check the spelling of --output-format, stdout/stderr separation and parsing of individual NDJSON lines. For schema errors, check that the file is readable and validate the response yourself. For batch errors, distinguish partial results, exit codes and continuation after failure. Do not replace safe automation with dangerous permission modes.
Next: CI/CD, permissions, settings.