Your code is never stored. Processing exclusively in EU data centers. GDPR-compliant.
View our security standardsLurus Code – CLI
The Lurus Code CLI is invoked with the `lurus` command and provides a complete AI-powered development workflow directly in your terminal.
npm install -g @scramble-cloud/lurus-code-cli Installation & Basics
Install the CLI globally via npm and get started in seconds.
npm install -g @scramble-cloud/lurus-code-cli lurus [command] [options] Without a command: starts interactive chat
Configuration Files
~/.lurus/auth.json Authentication data (JWT / API key) ~/.lurus/settings.json Global settings (model, MCP servers) ./.lurus/settings.json Project-specific settings LURUS.md Project context for the AI agent .lurus/rules/*.md Project rules .lurus/commands/*.md Custom slash commands Authentication
Register, log in, and manage your Lurus Code account.
register
Creates a new Lurus Code account via a secure browser-based device flow.
lurus register How it works
- 1 The CLI sends a request to
/auth/device/codeand receives a temporary device code. - 2 Your browser opens automatically on the registration page.
- 3 A short user code (e.g.
ABC-123) appears in the terminal. - 4 After completing registration in the browser, enter the code.
- 5 The CLI polls
/auth/device/tokenuntil confirmed, then saves JWT tokens locally.
ℹ No browser available? The URL is shown manually in the terminal.
ℹ The code expires after a few minutes (configurable via backend).
login
Authenticates with an existing Lurus Code account. Supports three different methods.
lurus login [options] Options
(none) Browser-based device flow (default) --api-key Login with API key (no browser required) --email Login with email address and password ℹ Stored in: ~/.lurus/auth.json
Methods
Method 1 – Browser Flow (default)
lurus login Opens browser → enter one-time code → done
Method 2 – Email & Password
lurus login --email Method 3 – API Key
lurus login --api-key logout
Logs out the current user and deletes local authentication data.
lurus logout [options] Options
(none) End current session only --all Log out from all devices simultaneously auth status
Displays the current authentication status and account information.
lurus auth status How it works
- 1 Reads local auth data from
~/.lurus/auth.json. - 2 Validates the session via GET
/auth/profile. - 3 Outputs name, email, plan, auth type, and API URL.
Output Fields
Chat & Interaction
Start an interactive session or send a single prompt. chat is the default command.
chat
lurus chat [prompt...] [options] lurus [prompt...] # identical – chat is the default Starts an interactive chat session with the AI agent, or sends a single prompt and exits. chat is the default command — it also runs without being explicitly specified.
Options
--model <model> -m Choose AI model (e.g. sonnet, opus, haiku) --prompt <text> -p Send a single prompt and exit --continue -c Resume the last session for this project --resume <id> -r Resume a specific session by ID --dangerously-skip-permissions — Skip all permission prompts (**CI/CD only!**) --pipe — JSON events on stdout, permission answers from stdin (IDE integration) --output-format <format> — Output format: text (default), stream-json, json --add-dir <dirs...> — Add additional directories to context --from-pr <number> — Load PR diff as initial context --json-schema <path> — JSON schema for validated structured output --permission-mode <mode> — Permission mode: default, acceptEdits, plan, bypassPermissions --chrome — Enable browser automation via Chrome DevTools Protocol --debug — Enable verbose debug output Examples
lurus chat Start interactive session
lurus chat -p "Explain the architecture of this project" Send single prompt (no interactive session)
lurus chat -m opus Start with a specific model
lurus chat --continue Resume last session
lurus chat --resume abc123def456 Resume specific session by ID
lurus chat --from-pr 42 Load PR diff as context (requires git or gh CLI)
lurus chat -p "Write tests for auth.service.ts" --dangerously-skip-permissions CI/CD – non-interactive, auto-grant all permissions
lurus chat --pipe JSON output for IDE integration (VS Code extension etc.)
lurus chat -p "Analyze the code" --output-format json --json-schema ./schema.json Structured JSON output with schema validation
lurus chat --add-dir ./src --add-dir ./tests Add multiple directories to context
lurus chat --permission-mode plan Read-only, no file changes
Permission Modes
default Asks before every tool use acceptEdits File edits are automatically accepted plan Read-only – no changes possible bypassPermissions Automatically grant all permissions Interactive Mode – Keyboard Shortcuts
Type ? to show all available shortcuts.
!ls -la) Batch Processing
Process multiple prompts from a text file sequentially. Ideal for scripts, pipelines, and automating recurring tasks.
batch
lurus batch <file> [options] Processes multiple prompts from a text file sequentially. Ideal for scripts, pipelines, and automating recurring tasks.
Options
--model <model> -m — AI model to use --output-format <format> -o text Output format: text or json --continue-on-error — false Continue processing on errors File Format
Prompts are separated by --- (three dashes). Lines starting with # are comments and are ignored.
Examples
lurus batch prompts.txt Simple batch processing (text output)
lurus batch prompts.txt -o json JSON output for machine processing
lurus batch prompts.txt --continue-on-error Skip errors and process all prompts
lurus batch prompts.txt -m haiku Use a specific model (cheaper for simple tasks)
lurus batch prompts.txt -o json --continue-on-error > results.json Combination: JSON output and skip errors
Plugin Management
Plugins extend the Lurus Code CLI with additional slash commands and workflows. They can be installed globally or per project.
Official Plugins
lurus-security Security scanning with 4 phases and SARIF export /scan lurus-code-review Code review with HTML/JSON export /review lurus-commit AI-generated commit messages /commit lurus-docs Automatic documentation generation /docs lurus-test Test generation and TDD workflows /test, /tdd plugin install
lurus plugin install <nameOrPath> [options] Installs a plugin from the official registry, a local path, or installs all available plugins.
lurus plugin install lurus-security Install official plugin globally lurus plugin install all Install all official plugins at once lurus plugin install ./my-plugin Install from local development path lurus plugin install lurus-security --project Install for current project only plugin remove
lurus plugin remove <name> [options] Removes an installed plugin.
lurus plugin remove lurus-security Remove a single plugin lurus plugin remove all Remove all plugins lurus plugin remove lurus-docs --project Remove project-specific plugin plugin list
lurus plugin list Lists all installed plugins and available official plugins.
MCP Server Management
MCP (Model Context Protocol) enables integration of external tools into the AI agent. MCP servers provide the agent with additional tools (e.g. database access, external APIs, filesystem tools).
mcp add
lurus mcp add <name> --command <cmd> [options] Adds a new MCP server to the configuration.
--command <cmd> Command to start the server **(required)** --args <args...> Arguments for the server command --env <pairs...> Environment variables in KEY=VALUE format --trust Trust the server (no permission prompts for its tools) --project Add to project scope (default: global) lurus mcp add filesystem --command npx --args @modelcontextprotocol/server-filesystem / Add filesystem server
lurus mcp add github --command npx --args @modelcontextprotocol/server-github --env GITHUB_TOKEN=ghp_xxx GitHub server with token
lurus mcp add my-server --command ./server.sh --trust Trusted local server (no confirmation on tool use)
lurus mcp add db-tools --command npx --args mcp-db-server --project Project-specific database server
mcp remove
lurus mcp remove <name> [options] Removes a configured MCP server.
lurus mcp remove filesystem Remove global server lurus mcp remove db-tools --project Remove project server mcp list
lurus mcp list Lists all configured MCP servers (global and project-specific).
CLI Management
Keep the CLI up to date and configure shell completions.
update
Updates the Lurus Code CLI to the latest available version.
lurus update [options] Options
--check Check if an update is available without installing How it works
- 1 Reads the currently installed version.
- 2 Queries the npm registry for the latest version (
npm view @lurus/code version). - 3 Runs
npm update -g @lurus/codeif an update is available.
Examples
lurus update --check Check if an update is available
lurus update Install the update
completions
Generates shell completion scripts for tab completion of all lurus commands and options.
lurus completions <shell> ℹ After setup, tab completion works for all commands, options, and arguments.
Shell Setup
echo 'eval "$(lurus completions bash)"' >> ~/.bashrc && source ~/.bashrc echo 'eval "$(lurus completions zsh)"' >> ~/.zshrc && source ~/.zshrc lurus completions fish > ~/.config/fish/completions/lurus.fish CI/CD Commands
These commands are optimized for automated pipelines: headless (no browser), with defined exit codes, and optional GitHub integration.
security-ci
Runs an AI-powered security scan in CI/CD mode. Analyzes code in 4 phases and outputs results as SARIF, JSON, HTML, or text.
lurus security-ci [options] Options
--model <model> — Override AI model --format <format> sarif Output format: sarif, json, html, text --output <path> lurus-security-results.sarif Output file --fail-on <severity> high Exit code ≠ 0 at this severity or higher --diff — Scan only changed files (via git diff) --diff-base <ref> HEAD Git ref for diff comparison --no-upload — Do not upload results to backend --pr-comments — Post findings as PR review comments --comment-min-severity <severity> medium Minimum severity for PR comments Phases
[1/4] Discovery Analyze files and project structure [2/4] Analysis Identify security vulnerabilities [3/4] Verification Verify findings (remove false positives) [4/4] Remediation Generate concrete fix suggestions Exit Codes
Examples
lurus security-ci Standard scan with SARIF output
lurus security-ci --diff --format json --output results.json Scan only changed files (ideal for PRs)
lurus security-ci --diff --diff-base main Compare against main branch
lurus security-ci --fail-on medium Fail already at medium severity
lurus security-ci --pr-comments --comment-min-severity high With PR comments (in GitHub Actions)
lurus security-ci --format html --output security-report.html Generate HTML report for developers
- name: Lurus Security Scan
run: lurus security-ci --diff --pr-comments
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} total_findings, blocking_findings, passed code-review-ci
Runs an AI-powered code review in CI/CD mode. Supports automatic PR comments and verdicts (APPROVE / REQUEST_CHANGES).
lurus code-review-ci [options] Options
--model <model> — Override AI model --format <format> json Output format: json, html, text --output <path> lurus-code-review-results.json Output file --fail-on <severity> high Exit code ≠ 0 at this severity or higher --full — Review entire project (default: git diff) --staged — Review only staged changes --diff-base <ref> — Git ref for diff comparison --pr-comments — Post findings as PR review comments --verdict — Submit PR review verdict (APPROVE / REQUEST_CHANGES) --comment-min-severity <severity> medium Minimum severity for PR comments Phases
[1/4] Discovery Identify changed files [2/4] Analysis Analyze code quality and patterns [3/4] Verification Validate findings [4/4] Suggestions Create concrete improvement suggestions Exit Codes
Verdicts
approve Code is fine, PR can be merged needsChanges Changes required (REQUEST_CHANGES) comment Comments only, no formal verdict Examples
lurus code-review-ci Standard review of current git diff
lurus code-review-ci --full Review entire project
lurus code-review-ci --staged Only staged changes (before commit)
lurus code-review-ci --format html --output review.html --pr-comments HTML report with PR comments
lurus code-review-ci --pr-comments --verdict With automatic verdict (APPROVE or REQUEST_CHANGES)
lurus code-review-ci --diff-base develop Compare against feature branch
- name: Lurus Code Review
run: lurus code-review-ci --pr-comments --verdict
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} Slash Commands (in Chat)
Slash commands are entered within an active lurus chat session. They always start with /. Tab completion is available.
/help shows all available commands with descriptions.
Session & Info
/help Shows all available slash commands with short descriptions.
/status Shows the full session status: current model and interaction mode, session ID and number of turns, session cost and account balance, token usage (input / output), files in context.
/cost Compact display of token usage and session cost (model, messages, input tokens, output tokens, session cost, balance).
/stats Detailed session statistics: duration, model, mode, turns, tokens, files in context, number of loaded tools.
/doctor Environment diagnostics – checks and shows: Node.js version, Git version and status, current directory and branch, API URL and connection status, model, mode, CLI version, and OS.
/report Generates a session analysis report.
/report HTML report (opens in browser) /report --json JSON export to lurus-report.json /report --json path/to/file.json JSON at a specific path /changelog Generates a CHANGELOG.md entry in Keep-a-Changelog format from the git log since the last tag.
/mermaid Generates Mermaid diagrams from the codebase.
/mermaid Project architecture diagram /mermaid database schema Database schema diagram /mermaid authentication flow Authentication flow diagram /vim Shows instructions for enabling Vim mode in the shell (~/.inputrc).
Configuration & Project
/config Shows the current configuration: API URL, model, prompt caching, max tokens, fallback model, utility model, model aliases, notifications, bypass-permissions status, loaded context sources (LURUS.md, rules).
/init Analyzes the current project and generates a LURUS.md file with: project description, tech stack, project structure, coding conventions, build/test/lint commands, and architectural decisions.
/init # Analyzing project and generating LURUS.md...
/rules Manages project rules (stored in .lurus/rules/*.md).
/rules List all rules /rules show <name> Show rule content /rules create [name] Create new rule (template) /permissions Manages persistent permissions (created by choosing [a]lways on tool requests).
/permissions Show all saved permissions /permissions clear Reset project permissions /permissions clear global Reset global permissions /theme Sets the terminal color scheme.
/theme dark Dark theme /theme light Light theme /theme auto Automatic (follows terminal setting) /statusline Controls the terminal status bar.
/statusline Show current status bar /statusline on Permanently enable status bar /statusline off Disable status bar Session Management
/resume Shows previous sessions for the current project and allows resuming them.
/resume Show all sessions /resume auth Filter sessions by keyword To continue: lurus chat --resume
/sessions Manages sessions.
/sessions Sessions for current project /sessions here Sessions in current directory /sessions all All sessions across all projects /sessions delete <id> Delete a session /recall Searches all sessions for a term.
/recall authentication Find sessions containing "authentication" /recall --load <id> Load and restore found session /clear Clears the conversation history of the current session (cannot be undone).
/save Exports the current session as a Markdown file.
/save Saves as lurus-session-<timestamp>.md /save my-session.md Save to a specific path /rewind Selective rollback.
/rewind chat Remove last messages from conversation /rewind code Undo last file changes (checkpoint) Context Management
/context Shows context window utilization: system prompt, directory tree, conversation tokens, total used vs. remaining.
/add Adds files or directories to the context.
/add src/auth.service.ts/add src/auth/ tests//add package.json README.md /drop Removes files from the context.
/drop src/auth.service.ts/drop tests/ /copy Copies the last AI response to the clipboard (macOS, Linux, Windows).
/paste Pastes an image from the clipboard into the chat (for visual analysis like UI screenshots).
/compress / /compact Compresses the conversation history to free up context window space. Old messages are summarized via LLM. Shows the number of tokens saved. /compact is an alias for /compress.
Code Indexing
/indexing Manages semantic code indexing (RAG – Retrieval Augmented Generation).
/indexing Show status (chunks, files, quota) /indexing on Enable indexing /indexing off Disable indexing /indexing rebuild Delete index and rebuild /indexing clear Reset local index + backend quota Git & GitHub
/git Executes Git commands directly from chat.
/git status/git log --oneline -10/git diff HEAD~1/git branch -a /commit Generates AI commit messages for staged changes.
/commit AI generates commit message /commit "my message" Commit with custom message directly - 1 Checks if changes are staged.
- 2 If not: asks whether to stage all changes.
- 3 AI analyzes the diff and generates a commit message.
- 4 Confirmation: `[y]es / [n]o / [e]dit`
/create-pr Creates a pull request with AI-generated title and body.
/create-pr Auto-generated title and body /create-pr --draft Create as draft PR /create-pr --reviewer username Add reviewer /create-pr --label bug Add label Requires: GitHub CLI (gh) installed and authenticated.
/fix-issue Analyzes and fixes a GitHub issue automatically.
/fix-issue 42
- 1 Loads issue details via `gh`.
- 2 Creates branch `fix/issue-42`.
- 3 AI analyzes the codebase and implements the fix.
/analyze-issue Analyzes a GitHub issue (read-only, no changes).
/analyze-issue 42
/fix-pr Automatically fixes open PR review comments.
/fix-pr
Loads all review comments of the current PR and implements the suggested corrections.
/worktree Manages Git worktrees.
/worktree create <branch> Create new worktree /worktree list List all worktrees /worktree switch <branch> Switch to a worktree Tools & Tests
/tools Lists all available agent tools.
/tools List names only /tools desc With descriptions /web Loads the content of a URL and adds it to the chat context.
/web https://docs.example.com/api
/lint Runs the configured linter.
/lint npm run lint /lint fix npm run lint -- --fix /test Runs tests.
/test npm test /test npm run test:unit Custom command /test jest auth.spec.ts Specific test file /tdd TDD workflow (Test-Driven Development).
/tdd <feature> Start TDD cycle (Red → Green → Refactor) /tdd on Enable TDD guard (warn mode) /tdd strict TDD guard (strict mode, blocks without tests) /tdd off Disable TDD guard /tdd-implement Implements code for already existing, failing tests. The AI runs npm test, implements code for each failing test, and ensures no regressions occur.
/tdd-implement
/edit Opens the configured editor ($EDITOR) for multi-line input. After saving, the content is sent as a prompt.
/edit # Opens vi/vim/nano/code depending on $EDITOR variable
/diff Shows all file changes since session start (changed files and colorized diff patch).
/diff
/undo Undoes the last file changes (checkpoint-based).
/undo # Restoring to: Before auth.service.ts edit (14:32:15) # ✓ Restored auth.service.ts, user.service.ts
Model & Mode
/model Shows or changes the AI model for the current session.
/model Show current model and available models /model sonnet Switch to Claude Sonnet /model opus Switch to Claude Opus (more powerful) /model haiku Switch to Claude Haiku (faster/cheaper) Model aliases from the configuration are automatically resolved.
/utilitymodel Shows or changes the utility model (used for internal tasks like summarization).
/utilitymodel Show current utility model /utilitymodel haiku Set to Haiku (cheaper for internal tasks) /utilitymodel clear Reset to default /mode Switches the agent interaction mode.
/mode Show current mode and all available modes /mode agent Full tool access (default) /mode plan Read-only and planning, no changes /mode ask Read-only, Q&A mode /mode debug Systematic debugging agent Full tool access – can write and execute code plan Read-only – creates plans and analyses without changes ask Read-only – answers questions without tool use debug Systematic debugging (best results with IDE connection) /max Toggles max mode (delays automatic context compaction). In max mode, automatic compaction is triggered at 85% utilization (default: 50%).
/max
/thinking Toggles extended thinking on or off. Extended thinking allows the model to work through complex problems step by step (improves quality on complex tasks, costs more tokens).
/thinking Enable /thinking off Disable Plugins & Extensions
/plugins Manages plugins directly from chat.
/plugins List installed plugins /plugins install lurus-security Install plugin /plugins install all Install all official plugins /plugins remove lurus-docs Remove plugin /mcp Shows MCP server status and available tools.
/mcp Show all servers and their tools /mcp restart <name> Restart a server /commands Lists all custom commands, skills, and custom agents (from .lurus/commands/*.md, skills with active/inactive status, custom agents with tools and model).
/commands
/skills Manages skills (reusable AI workflows).
/skills List all skills /skills activate <name> Activate skill /skills deactivate <name> Deactivate skill /skills audit Check skills for issues /skillify Converts the current session into a reusable skill. The AI analyzes the session, identifies repeatable processes, and creates a SKILL.md file in .lurus/skills/ or ~/.lurus/skills/.
/skillify
/create-hook Creates hook boilerplate for event-based automation.
/create-hook PreToolUse my-hook Create shell hook /create-hook PostToolUse my-hook --ts Create TypeScript hook PreToolUse Before every tool execution PostToolUse After successful tool execution PostToolUseFailure After failed tool execution SessionStart When a session starts SessionEnd When a session ends UserPromptSubmit On every prompt input SubagentStart When a subagent starts Stop When the agent stops PreCompact Before context compaction Notification On notifications /hooks Manages hooks.
/hooks validate Check hooks.json for errors Review & Security
/review / /code-review Runs an AI code review (requires lurus-code-review plugin).
/review Review uncommitted changes /review --full Review entire project /review --staged Only staged changes /review --diff-base main Compare against branch/ref /review --tier max Use best models (Opus etc.) /review --tier eu Use EU models only /review --html Generate HTML report /review --json output.json JSON export /review --model opus Override model for all phases /scan / /security-review Runs a security scan (requires lurus-security plugin).
/scan Scan entire project /scan --diff Only changed files /scan --diff-base main Compare against branch/ref /scan --tier max Best models /scan --tier eu EU models only /scan --html Generate HTML report /scan --json output.json JSON export /scan --model opus Override model Orchestration & IDE
/orchestrate Starts a multi-agent workflow.
/orchestrate Show available workflows /orchestrate feature <prompt> Feature development /orchestrate bugfix <prompt> Bug fixing /orchestrate refactor <prompt> Code refactoring /orchestrate security <prompt> Security review /orchestrate review <prompt> Code review /orchestrate auto <spec> Autonomous loop until spec is met Autonomous loop with limits:
/orchestrate auto "Implement full user auth" --max-iterations 30 --max-tokens 5000000 --max-cost 50 --max-subtasks 25 feature Feature development with planning, implementation, and tests bugfix Systematic bug analysis and fixing refactor Code quality improvement without behavior changes security Security analysis and hardening review Comprehensive code review auto Autonomous loop: break task into subtasks and solve iteratively /ide Manages the IDE connection (VS Code).
/ide Show connection status /ide enable Connect to VS Code /ide disable Disconnect - ✓ Diff view for file changes directly in VS Code
- ✓ Inline diagnostics (linter/compiler errors in chat context)
- ✓ Debug session integration
/quit / /exit Ends the chat session.
/quit Exit the session /exit Exit the session (alias) Quick Reference
CLI Commands (Top-Level)
lurus register lurus login lurus logout [--all] lurus auth status lurus chat lurus chat -p "..." lurus chat -c lurus batch <file> lurus plugin install <name> lurus plugin remove <name> lurus plugin list lurus mcp add <name> lurus mcp remove <name> lurus mcp list lurus update [--check] lurus completions <shell> lurus security-ci lurus code-review-ci Slash Commands (in Chat)
/help, /status, /cost, /stats, /doctor, /report, /changelog, /mermaid
/config, /init, /rules, /permissions, /theme, /statusline
/resume, /sessions, /recall, /clear, /save, /rewind
/context, /add, /drop, /copy, /paste, /compress, /compact
/indexing
/git, /commit, /create-pr, /fix-issue, /analyze-issue, /fix-pr, /worktree
/tools, /web, /lint, /test, /tdd, /tdd-implement, /edit, /diff, /undo
/model, /utilitymodel, /mode, /max, /thinking
/plugins, /mcp, /commands, /skills, /skillify, /create-hook, /hooks
/review, /code-review, /scan, /security-review
/orchestrate, /ide
/quit, /exit
Best Practices & Code Examples
Practical examples, common pitfalls, and tips for getting the most out of the Lurus Code CLI.
Authentication
Use API Keys in CI/CD – Never Browser Flow
Browser-based login requires user interaction and does not work in headless environments. Always use API keys for pipelines.
✅ Correct – API key via environment variable
# Set in CI/CD secrets (e.g. GitHub Actions) export LURUS_API_KEY=lurus_your_key_here # Or pass directly to command LURUS_API_KEY=lurus_xxx lurus security-ci --diff
❌ Wrong – Browser flow in CI/CD
# This will hang in a headless environment! lurus login # Requires browser interaction
Store the API key as a GitHub Secret (LURUS_API_KEY) and inject it via env: in your workflow.
Always Verify Authentication After Login
After logging in, always verify that the session is active before starting a session.
✅ Correct – Verify after login
lurus login lurus auth status # ✓ Authenticated # Name: Jane Developer # Plan: pro
If lurus auth status shows "Not authenticated", run lurus login again or check your API key.
Secure Logout from All Devices
When changing devices or suspecting a compromised session, log out from all devices.
✅ Correct – Log out from all devices
# Log out from all devices (e.g. when changing laptops) lurus logout --all # Then log in again on the new device lurus login
Chat & Interaction
Use --permission-mode plan for Read-Only Analysis
When you only want to analyze code without making changes, use plan mode. This prevents accidental file modifications.
✅ Correct – Read-only analysis
# Analyze architecture without making changes lurus chat -p "Explain the authentication flow" --permission-mode plan # Or switch mode inside the chat lurus chat > /mode plan > Analyze all API endpoints in src/routes/
❌ Suboptimal – Default mode for read-only tasks
# In default mode, the agent might modify files unexpectedly lurus chat -p "Explain the authentication flow" # Agent might create files or make changes
Use /mode plan inside an active session to switch to read-only mode at any time.
Load Context Before Asking Questions
Add relevant files to the context before asking complex questions. This gives the AI agent better information.
✅ Correct – Load context first
lurus chat > /add src/auth/ src/users/ tests/auth/ > /indexing on > Now explain the complete authentication flow and identify potential security issues
❌ Suboptimal – Ask without context
lurus chat > Explain the authentication flow # AI agent has no file context and gives generic answers
Use /context to check how much of the context window is already used.
Resume Sessions Instead of Starting New Ones
Sessions preserve context and history. Resuming is more efficient than starting fresh every time.
✅ Correct – Resume last session
# Continue where you left off lurus chat -c # Or resume a specific session lurus chat --resume abc123def456 # Inside chat: search past sessions > /recall "authentication refactor"
Use /save my-feature.md to export important sessions as Markdown for later reference.
Use --output-format json for Scripting
For automated workflows, use JSON output to process AI responses programmatically.
✅ Correct – JSON output for scripting
# Get structured output and process with jq lurus chat -p "List all public API endpoints as JSON array" \ --output-format json \ --json-schema ./api-schema.json | jq '.endpoints' # Stream JSON for real-time processing lurus chat -p "Analyze this file" --output-format stream-json
Batch Processing
Structure Prompt Files with Comments
Use comments (#) and clear separators (---) to organize batch files for maintainability.
✅ Correct – Well-structured prompt file
# prompts.txt # ============================================ # Batch: Documentation Generation v1.0 # Run: lurus batch prompts.txt -o json # ============================================ # Prompt 1: Auth module Analyze src/auth/auth.service.ts and generate JSDoc comments for all public methods --- # Prompt 2: User module Analyze src/users/user.service.ts and generate JSDoc comments for all public methods --- # Prompt 3: Summary Create a README.md overview for the src/ directory
❌ Suboptimal – Unstructured prompt file
Analyze auth.service.ts --- Analyze user.service.ts --- Create README
Use -m haiku for simple documentation tasks to reduce costs significantly.
Always Use --continue-on-error in CI/CD
In pipelines, a single failing prompt should not abort the entire batch. Use --continue-on-error and check the exit code.
✅ Correct – Error-tolerant batch in CI
# In GitHub Actions
- name: Generate Documentation
run: |
lurus batch doc-prompts.txt \
-o json \
--continue-on-error \
> batch-results.json
# Check how many succeeded
jq '.succeeded, .failed' batch-results.json ❌ Wrong – Batch without error handling
# One failing prompt aborts the entire batch lurus batch doc-prompts.txt # Exit code 1 = pipeline fails immediately
Use Cheaper Models for Simple Tasks
Not every task requires the most powerful model. Use haiku for simple documentation, sonnet for complex analysis.
✅ Correct – Model selection based on task complexity
# Simple documentation → haiku (fast & cheap) lurus batch simple-docs.txt -m haiku # Complex security analysis → opus (most powerful) lurus batch security-analysis.txt -m opus # Default → sonnet (good balance) lurus batch mixed-tasks.txt
Check token costs with /cost in an interactive session before running large batches.
Plugin Management
Install Plugins Per Project for Isolation
Use --project to install plugins only for the current project. This avoids conflicts between different projects.
✅ Correct – Project-specific installation
# Install security plugin only for this project cd /path/to/my-project lurus plugin install lurus-security --project # Verify project plugins lurus plugin list # lurus-security v1.2.0 [project]
❌ Suboptimal – Global installation for all projects
# Installs globally – affects all projects lurus plugin install lurus-security # May conflict with other project configurations
Use global installation only for plugins you use in every project (e.g. lurus-commit).
Install All Plugins for a Full Setup
For a complete development environment, install all official plugins at once.
✅ Correct – Full setup with one command
# Install all official plugins globally lurus plugin install all # Verify installation lurus plugin list # lurus-security v1.2.0 [global] # lurus-code-review v1.0.0 [global] # lurus-commit v1.0.0 [global] # lurus-docs v1.0.0 [global] # lurus-test v1.0.0 [global] # Now available in chat: # /scan, /review, /commit, /docs, /test, /tdd
MCP Server Management
Use --trust Only for Local, Verified Servers
The --trust flag disables permission prompts for a server's tools. Only use it for servers you fully control.
✅ Correct – Trust only local servers
# Local server you wrote yourself → trust is OK lurus mcp add my-db-tools --command ./scripts/db-mcp.sh --trust # External server → never trust without review lurus mcp add filesystem --command npx --args @modelcontextprotocol/server-filesystem / # (No --trust: each tool use requires confirmation)
❌ Dangerous – Trust external servers
# Never do this with untrusted servers! lurus mcp add unknown-server --command npx --args some-unknown-mcp --trust # Could execute arbitrary code without confirmation
Use /mcp in chat to see which tools a server provides before trusting it.
Use Environment Variables for Secrets
Pass API tokens and secrets via --env, never hardcode them in scripts.
✅ Correct – Secrets via environment variables
# Pass GitHub token via --env
lurus mcp add github \
--command npx \
--args @modelcontextprotocol/server-github \
--env GITHUB_TOKEN=$GITHUB_TOKEN
# Or read from environment
lurus mcp add github \
--command npx \
--args @modelcontextprotocol/server-github \
--env GITHUB_TOKEN=${GITHUB_TOKEN} ❌ Wrong – Hardcoded secrets
# Never hardcode tokens! lurus mcp add github \ --command npx \ --args @modelcontextprotocol/server-github \ --env GITHUB_TOKEN=ghp_abc123xyz # Visible in shell history!
Use Project Scope for Project-Specific Tools
Database servers, project-specific APIs, and local tools should be configured per project.
✅ Correct – Project-specific MCP server
# Project database server → only for this project cd /path/to/my-project lurus mcp add db-tools \ --command npx \ --args mcp-postgres-server \ --env DATABASE_URL=$DATABASE_URL \ --project # Global tools (filesystem, GitHub) → global lurus mcp add filesystem \ --command npx \ --args @modelcontextprotocol/server-filesystem /
CI/CD Commands
Always Use --diff in PRs – Never Scan the Entire Project
In PR workflows, only scan changed files. Full project scans are slow and waste credits.
✅ Correct – Scan only changed files
# In GitHub Actions on pull_request events
- name: Lurus Security Scan
run: lurus security-ci --diff --pr-comments
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
LURUS_API_KEY: ${{ secrets.LURUS_API_KEY }} ❌ Suboptimal – Full scan on every PR
# Scans entire project on every PR – slow & expensive! - name: Lurus Security Scan run: lurus security-ci # No --diff flag
Use --diff-base main to compare against the main branch instead of HEAD.
Configure Severity Thresholds Progressively
Start with --fail-on critical, then lower the threshold as the team fixes existing issues.
✅ Correct – Progressive severity thresholds
# Phase 1: Only block on critical issues lurus security-ci --diff --fail-on critical # Phase 2: After fixing critical issues lurus security-ci --diff --fail-on high # Phase 3: Strict mode lurus security-ci --diff --fail-on medium
Use --no-upload if you want to run scans without uploading results to the backend.
Use GitHub Actions Outputs for Notifications
Lurus CI commands set GitHub Actions outputs that you can use for Slack/Teams notifications.
✅ Correct – Use outputs for notifications
- name: Lurus Security Scan
id: security
run: lurus security-ci --diff --pr-comments
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
LURUS_API_KEY: ${{ secrets.LURUS_API_KEY }}
- name: Notify on Findings
if: steps.security.outputs.blocking_findings > 0
uses: slackapi/slack-github-action@v1
with:
payload: |
{"text": "⚠️ ${{ steps.security.outputs.total_findings }} security findings found!"} Full CI/CD Pipeline: Security + Code Review
Combine security scan and code review in a single workflow for complete AI-powered quality gates.
✅ Complete pipeline example
name: AI Code Quality
on:
pull_request:
branches: [main, develop]
jobs:
ai-quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Full history for diff
- name: Install Lurus
run: npm install -g @scramble-cloud/lurus-code-cli
- name: Security Scan
id: security
run: lurus security-ci --diff --pr-comments --fail-on high
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
LURUS_API_KEY: ${{ secrets.LURUS_API_KEY }}
- name: Code Review
id: review
run: lurus code-review-ci --pr-comments --verdict
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
LURUS_API_KEY: ${{ secrets.LURUS_API_KEY }}
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: lurus-security-results.sarif Slash Commands
Initialize Every New Project with /init
Run /init at the start of each new project to give the AI agent full project context.
✅ Correct – Project initialization
# In the project root lurus chat > /init # Analyzing project and generating LURUS.md... # ✓ LURUS.md created # The AI agent now knows: # - Tech stack (TypeScript, React, PostgreSQL) # - Project structure # - Build/test/lint commands # - Coding conventions
Update LURUS.md regularly as the project evolves. The AI agent reads it at every session start.
Use /compress to Extend Long Sessions
When the context window fills up, compress the conversation history instead of starting a new session.
✅ Correct – Compress instead of restart
# Check context usage > /context # Context utilization: ████████░░ 78.3% # Compress when approaching 80% > /compress # ✓ Compressed 45,123 → 8,234 tokens (saved 36,889 tokens) # Continue working > Continue implementing the OAuth2 flow
❌ Suboptimal – Start new session on context full
# Loses all context and history! > /quit lurus chat # New session – AI has no memory of previous work
Use /tdd for Quality-Driven Development
The TDD workflow ensures code quality by writing tests first. Use /tdd on for permanent guard mode.
✅ Correct – TDD workflow
# Enable TDD guard for the session > /tdd on # ✓ TDD guard enabled (warn mode) # Start TDD cycle for a feature > /tdd UserAuthentication # [RED] Writing failing tests... # [GREEN] Implementing minimal code... # [REFACTOR] Improving code quality... # Or implement for existing failing tests > /tdd-implement # Running npm test... 3 tests failing # Implementing fixes...
Use /orchestrate for Complex Multi-Step Tasks
For complex features that require planning, implementation, and testing, use orchestration instead of a single prompt.
✅ Correct – Orchestrated feature development
# Complex feature → use orchestration
> /orchestrate feature "Add OAuth2 login with Google and GitHub"
# Autonomous loop for large tasks
> /orchestrate auto "Implement complete user management with RBAC" \
--max-iterations 20 \
--max-cost 30
# Review all changes after orchestration
> /diff ❌ Suboptimal – Single prompt for complex tasks
# Too complex for a single prompt – inconsistent results > Implement complete OAuth2 login with Google and GitHub, including tests, documentation, and error handling
Use /thinking for Complex Architectural Decisions
Enable extended thinking for complex problems that require deep analysis.
✅ Correct – Extended thinking for complex problems
# Enable extended thinking > /thinking # ✓ Extended thinking enabled # Now ask complex architectural questions > Analyze the current database schema and propose a migration strategy to support multi-tenancy without breaking existing data # Disable for simple tasks (saves tokens) > /thinking off
Extended thinking costs more tokens but significantly improves quality for complex architectural decisions.
Common Errors & Solutions
Error: Not authenticated No valid session or expired token.
Run `lurus login` or set `LURUS_API_KEY` as environment variable.
# Solution 1: Re-login lurus login # Solution 2: Use API key export LURUS_API_KEY=lurus_your_key lurus auth status
Error: Rate limit exceeded Too many requests in a short time period.
Wait a few seconds and retry. Use `--continue-on-error` in batch mode.
# In batch mode: skip rate limit errors lurus batch prompts.txt --continue-on-error # Check your quota lurus auth status # Balance: 0.50 € (low!)
Context window full (100%) The conversation history is too long.
Use `/compress` to summarize the history, or `/clear` to start fresh.
# Option 1: Compress (preserves context) > /compress # Option 2: Clear (loses history) > /clear # Option 3: Enable max mode to delay compression > /max
Exit code 2: Scan failed (technical error) Network error, authentication problem, or internal error.
Check authentication status and network connection. Run with `--debug` for details.
# Check authentication lurus auth status # Run with debug output lurus security-ci --debug # Check if the issue is temporary lurus update --check # Is the CLI up to date?
Plugin not found after install Plugin installed in wrong scope (global vs. project).
Check with `lurus plugin list` and reinstall with correct scope.
# Check installed plugins lurus plugin list # Reinstall for current project lurus plugin install lurus-security --project # Or install globally lurus plugin install lurus-security
MCP server: connection refused Server process failed to start or port is blocked.
Restart the server with `/mcp restart <name>` and check logs.
# In chat: restart the server > /mcp restart my-server # Check server status > /mcp # filesystem ❌ disconnected # Remove and re-add lurus mcp remove my-server lurus mcp add my-server --command ./server.sh
Advanced Command Combinations
Complete PR Workflow
From feature development to merged PR – fully automated.
# 1. Start session and initialize project lurus chat > /init > /mode agent # 2. Develop feature with TDD > /tdd UserAuthentication # 3. Run all tests > /test # 4. Security check > /scan --diff # 5. Code review > /review --staged # 6. Commit and PR > /commit > /create-pr --reviewer team-lead
Automated Nightly Quality Report
A complete quality pipeline that runs every night and generates reports.
# nightly-quality.yml
name: Nightly Quality Report
on:
schedule:
- cron: '0 2 * * *' # Every night at 2am
jobs:
quality-report:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm install -g @scramble-cloud/lurus-code-cli
# Security scan → HTML report
- run: lurus security-ci --format html --output security.html
env:
LURUS_API_KEY: ${{ secrets.LURUS_API_KEY }}
# Code review → JSON report
- run: lurus code-review-ci --full --format json --output review.json
env:
LURUS_API_KEY: ${{ secrets.LURUS_API_KEY }}
# Batch: generate changelogs
- run: lurus batch nightly-prompts.txt -o json --continue-on-error
env:
LURUS_API_KEY: ${{ secrets.LURUS_API_KEY }}
- uses: actions/upload-artifact@v4
with:
name: quality-reports
path: |
security.html
review.json Multi-Repository Security Audit
Scan multiple repositories in parallel using a batch file.
# audit-prompts.txt # Security audit for all microservices Analyze src/auth-service/ for security vulnerabilities and generate a SARIF report --- Analyze src/payment-service/ for security vulnerabilities and generate a SARIF report --- Analyze src/user-service/ for security vulnerabilities and generate a SARIF report
# Run audit across all services lurus batch audit-prompts.txt -o json --continue-on-error > audit-results.json # Check results jq '.results[] | select(.status == "error")' audit-results.json
Interactive Session with Full MCP Setup
A fully configured session with GitHub, filesystem, and database tools.
# Setup (once) lurus mcp add github \ --command npx \ --args @modelcontextprotocol/server-github \ --env GITHUB_TOKEN=$GITHUB_TOKEN lurus mcp add filesystem \ --command npx \ --args @modelcontextprotocol/server-filesystem / lurus mcp add db \ --command npx \ --args mcp-postgres-server \ --env DATABASE_URL=$DATABASE_URL \ --project --trust # Start session lurus chat > /mcp # Verify all servers are connected > /indexing on # Enable semantic code search > /mode agent # Full tool access # Now the AI can: # - Read/write files via filesystem MCP # - Query GitHub issues/PRs # - Execute database queries # - Search the codebase semantically
Workflows in Action
See the most important CLI workflows as animated terminal demos. Click the replay button ↺ to restart any animation.
Demo 1: Login & Authentication
Authenticate with Lurus Code in seconds using browser OAuth.
Demo 2: First Chat Session
Start an interactive AI coding session with a single command.
Demo 3: Batch Processing
Process multiple AI tasks in sequence – perfect for CI/CD pipelines.
Demo 4: Security Scan
Run a full project security scan and generate a SARIF report for CI/CD.
Demo 5: Automated Code Review
Run an automated code review in CI and post the verdict as a PR comment.
Installation & Basics
Complete reference for all Lurus Code CLI commands. Learn how to use the AI coding agent from the terminal.