// Documentation

Learn — Command Reference

A comprehensive reference to leverage the full capabilities of Uneven AI. Learn how to configure your project, monitor terminal executions, query your codebase, and use advanced analysis tools.

Command Index

Uneven AI is executed directly via the terminal using the global command uneven <command>. Below is the organization of commands by logical categories:

1. Configuration & Diagnostics
init Initialize project and create configurationinfo System diagnostics and hardware statuslicense Activation and verification of licenses
2. Development & Monitoring
watch Real-time active process watcherautofix Silent background file-save watcher Proindex Map codebase and knowledge targets
3. Interaction & Codebase Queries
uneven Interactive Conversational Shellask One-off natural language codebase querieschat Continuous back-and-forth codebase chatexplain Step-by-step code logic explainer Proaskf Surgical file creator and task editor Prodocs Automated API documentation generator
4. Validation, Testing & History
test Auto-detect and run affected test suitesci Unified validation runner for CI pipelines Proreview Automated AI code review of Git diffs Prodiff / undo Inspect, revert, or restore AI changes
5. Security & Data Analysis
scan Local vulnerability and dependency security scanpentest Automated static and active penetration tests Teamanalyze Natural language database analyst and dashboards Proremote-shell Secure automation listener gate Teamwebhooks Real-time Slack/Discord fail alerts Team

Security & Sandbox Architecture

Uneven AI is built on a local-first, zero-trust security architecture. While it does not isolate your workspace inside a heavy virtual machine or Docker container, it enforces strict sandbox boundaries directly at the engine level:

  • Path-Traversal Boundaries (Physical Sandbox): Every file-read, write, or update operation is programmatically bound to the project root. The engine intercepts and blocks any attempts to read or write files outside the workspace (including absolute paths or parent directory traversals like ../).
  • Context Isolation: All vectorized intelligence, index metadata, cache, and history logs are stored strictly inside your local .uneven/ directory. There is no shared cross-project data or centralized index.
  • Database Audit Gates: Database queries are filtered through a multi-tier sandbox. Generated SQL queries are audited to block destructive commands (DROP, DELETE, UPDATE) and restrict reading only to columns and tables declared in your configuration schema whitelist. Sensitive fields are redacted locally before any processing.
  • Sovereign Local Execution: Because the execution engine runs as a compiled native binary, all indexing, file processing, and log formatting are executed locally on your hardware. Zero telemetry is dispatched, and your code never leaves your machine.
  • Fail-Safe Backups (.uneven/obsolete): Before any AI-generated code patch is written, Uneven takes an automated backup snapshot of the target files, allowing instant restoration if the changes need to be reverted.

1. Configuration & Diagnostics

uneven init

Initializes the Uneven AI structure at the root of your project directory.

This interactive questionnaire helps generate your uneven.config.ts configuration file, sets up the local LLM cérebro/model if running offline, adds log folders to your .gitignore, and creates the internal .uneven/ state directory.

terminal
uneven init

uneven info

Displays detailed diagnostic information about the local runtime environment, including GPU acceleration status, active hardware resources, and the selected intelligence cérebro/model.

terminal
uneven info

uneven license <action>

Manages your local license activation key to unlock Pro and Team features.

terminal
# Activate your license key
uneven license activate YOUR_LICENSE_KEY

# Check active plan and subscription status
uneven license status

# Deactivate and release the key from this machine
uneven license deactivate

2. Development & Monitoring

uneven watch [commands...]

Starts the active development process watcher. It executes your local dev server or compiler and monitors console outputs for error signatures in real time.

Upon intercepting a compilation or runtime error, Uneven AI automatically locates the source file, analyzes the affected lines, and proposes a surgical fix tailored to your project context.

terminal
# Monitor using the dev command configured in uneven.config.ts
uneven watch

# Override and run a specific development command directly
uneven watch npm run dev

# Suppress specific warnings and specify cérebro/model override
uneven watch --ignore "**/warnings/*" --model gemini-2.5-flash
autoFix: false Default

Displays the proposed changes as a side-by-side Git-style diff in the terminal and waits for your explicit confirmation before modifying files.

autoFix: true

Applies and saves the surgical patch directly to the file as soon as the error occurs, generating a local Git commit automatically for easy tracking and rollbacks.

uneven autofix (Pro Feature)

Starts a silent background daemon that listens to file-saving events directly from your code editor.

Every time you save a file, the background service verifies syntax and integrity asynchronously. If a syntax break or logical error is introduced, it suggests or applies the fix instantly before you even switch focus back to the terminal.

terminal
# Start the background file-watching daemon
uneven autofix

# Stop the background daemon
uneven autofix --off

uneven index

Indexes your source files, local documentation, and configured knowledge targets to keep the local intelligence cérebro context fresh.

terminal
# Incremental indexing (scans only modified files)
uneven index

# Force full re-indexing of all configured targets
uneven index --full

# Preview which files match the indexing scope without applying
uneven index --dry-run
◈ Pro Highlight

Multi-Brain Intelligent Routing

With the Pro plan, you gain fine-grained control over which specific model or provider executes which command. This allows you to optimize speed, accuracy, and resource efficiency.

Simply configure multiple brains in the brains array of your uneven.config.ts, then map individual commands to specific cérebro IDs in the routing block:

uneven.config.tsTypeScript
export default {
  // Default model for general queries
  brain: { id: 'default', provider: 'local', model: 'llama3.2' },

  // Register multiple specialized model configurations (Pro Feature)
  brains: [
    { id: 'fast', provider: 'gemini', model: 'gemini-2.5-flash', temperature: 0.2 },
    { id: 'smart', provider: 'openai', model: 'gpt-4o', temperature: 0.1 }
  ],

  // Map specific tasks to specialized models (Pro Feature)
  routing: {
    watch: 'fast',    // Ultra-fast response loops for live dev monitoring
    review: 'smart',  // Deep reasoning capabilities for detailed Git reviews
    pentest: 'smart'  // Maximum precision for automated security audits
  }
}

3. Interaction & Codebase Queries

uneven Conversational Shell

Launches the Interactive Conversational Control Room. Perfect for developers who prefer interacting in natural language instead of memorizing strict CLI syntax. You can type conversational prompts to ask about your code or naturally trigger project tasks.

terminal
# Enter the conversational control shell
uneven

Inside the shell, you can type your prompts naturally without using quotation marks. The agent automatically distinguishes between reading (querying) and writing (modifying) code based on prefixes:

💡
How prompt formatting works:
  • Outside the shell (one-off commands): Always wrap prompts in quotes: uneven ask "query" or uneven askf "task".
  • Inside the shell (interactive): Do not use quotes. Write plain text queries directly (e.g. how is auth structured?). If you want to modify files, prefix the prompt with askf (e.g. askf create auth.ts).

Examples of interactive shell prompts (no quotes needed):

  • how is the user database schema structured? (General query — read-only)
  • explain src/auth.ts (File breakdown)
  • askf create a new express router in src/routes/user.ts (File modification — prefixed with askf)
  • watch my app or start monitoring (Utility command)
  • scan the directory for security bugs (Security scan)
  • revert last applied fix (Git revert)

uneven ask <question>

Performs a one-off query against your codebase directly from your terminal and returns the answer immediately.

terminal
# Ask a one-off question directly from your terminal
uneven ask "where is the JWT validation token generated?"

uneven chat

Starts a continuous back-and-forth interactive chat session to discuss your code, bounce ideas, or ask general programming questions with a rolling conversation history.

terminal
# Start an interactive continuous back-and-forth conversation
uneven chat

uneven explain <file> [focus] (Pro Feature)

Generates step-by-step explanations and structured summaries of legacy files (like COBOL or legacy scripts) or highly complex code architectures.

terminal
# Explain the logic of a legacy source file
uneven explain src/legacy/payroll.cob

# Focus the explanation on a specific class or function in the file
uneven explain src/server.ts handleIncomingMessage

uneven askf "<task>" (Pro Feature)

Creates new files or surgically edits existing files based on natural language task descriptions.

The command strictly respects physical project sandbox boundaries, preventing modifications to external folders.

terminal
uneven askf "create a helper function in src/utils/format.ts to format values as currency"

uneven docs <file> [symbol]

Generates comprehensive technical documentation or injects structured comments directly into function signatures.

terminal
# Generate a Markdown technical documentation file summarizing the structure
uneven docs src/services/user.ts --format md --out docs/user-service.md

# Inject a formatted JSDoc comment block directly above a function
uneven docs src/utils/math.ts calculateSum --format jsdoc

4. Validation, Testing & History

uneven test

Automatically identifies and runs the relevant test suite (Vitest, Jest, Pytest, Cargo Test, etc.) corresponding to your recent code modifications.

terminal
# Run tests associated with a specific file
uneven test --file src/controllers/auth.ts

uneven ci (Pro Feature)

Runs a unified validation pipeline in headless continuous integration (CI) environments, validating TypeScript compilation, unit tests, and security scans in a single pass.

terminal
# Execute the complete validation flow for CI pipelines
uneven ci

# Enable native annotations for GitHub Actions console and save a JSON log summary
uneven ci --github -o build-summary.json

uneven review (Pro Feature)

Conducts detailed and automated AI code reviews based on active Git modifications or history.

terminal
# Review changes currently in the Git staging area
uneven review --staged

# Compare modifications between your current branch and main with custom guidelines
uneven review --from main --context "ensure no sensitive credentials or keys are exposed"

uneven diff / undo / restore

Manual control commands to safely inspect, apply, revert, or restore modifications applied by the AI agent.

terminal
# List and inspect all pending AI-proposed fixes
uneven diff

# Apply a specific proposed change using its unique ID
uneven diff --apply suggestion-a8b2

# Revert the latest action or automatic commit created by the AI agent
uneven undo

# Restore the original state of a file from the internal cache history
uneven restore --file src/index.ts --list

5. Security & Data Analysis

uneven scan

Scans your local codebase and third-party dependencies for exposed API keys, hardcoded credentials, security anti-patterns, and compromised packages.

terminal
# Run a local security audit scan
uneven scan

# Generate detailed security audit reports in HTML and Markdown
uneven scan --report

uneven pentest (Team Feature)

Executes automated penetration testing. Supports both static security analysis and active target scans against configured endpoints.

terminal
# Run static analysis and generate an intrusion audit report
uneven pentest --report

# Run in active mode, declaring specific API route scopes for targeted testing
uneven pentest -m active --declare-scope "/api/v1/users,/api/v1/auth"

uneven analyze (Pro Feature)

Queries and analyzes databases or local files (CSV, Excel sheets) using natural language, translating text prompts into dynamic reports and visual dashboards.

Mode 1: Interactive SQL & BI Shell

Triggered when running the command without a prompt. Opens a dedicated SQL/BI control space to inspect schemas and run queries freely:

terminal
uneven analyze --db postgresql://user:pass@localhost:5432/mydb

Mode 2: Automated Logical Queries

Triggered by passing the --prompt argument. Generates instant insights and exports dashboards in custom formats:

terminal
# Generate an interactive HTML dashboard with charts and dark theme
uneven analyze --db postgresql://localhost/mydb --prompt "show category revenue this month" --report html --theme dark

# Compile and bundle the generated dashboard into a portable executable .exe file
uneven analyze --db mysql://localhost/store --prompt "weekly user registrations summary" --report html --package-exe

# Export the query results directly into a pre-formatted Excel spreadsheet
uneven analyze --db sqlite://local.db --prompt "monthly sales report" --report excel

uneven remote-shell (Team Feature)

Exposes a secure local listener port allowing external triggers or custom automation integrations (like Slack/Discord bots) to query the local intelligence agent.

terminal
uneven remote-shell

Webhook Notifications (Team Feature)

Pushes real-time alerts and error-watcher logs captured by the dev watcher directly to Discord, Slack, or generic webhook channels specified in your uneven.config.ts.

← Quick StartConfiguration →