Two command-line tools, not one
CodeDelta gives you two ways to work from the command line, and knowing which is which clears up most confusion:
1. The engine — codedelta old new — a compiled C++ tool that measures how code changed between two versions (SLOC/LLOC, churn, diffs). Fast, lean, measurement only. No AI.
2. The batch CLI — codedelta_server.py scan … — a headless command that runs the full analysis: change measurement plus the AI Audit and Agent Scan. This is how you invoke AI from the command line.
Both run unattended — in a terminal, a build pipeline, or a scheduled cron job. The difference is scope: the engine answers "what changed?"; the batch CLI answers that and "was this written by AI?" and "does this code use or launch AI?" — all without opening the graphical interface.
Need fast change metrics or a CI churn gate? Use the engine. Need AI authorship or agent-code detection on a schedule? Use the batch CLI. Both are covered below.
The engine vs the full application
CodeDelta has two layers. Understanding the split explains exactly what the command-line tool does and does not do.
The C++ engine is the command-line tool. The AI features live in the Python layer above it.
The engine does measurement only. The AI features — the AI Audit (authorship scoring) and the Agent Scan (detecting code that calls or launches AI) — live in the Python layer. You reach them either through the graphical interface or through the batch CLI (codedelta_server.py scan), which is a command-line front door to that same Python layer. So both the GUI and the batch CLI can run AI; the bare engine cannot.
| Engine | Batch CLI | |
|---|---|---|
| Command | codedelta old new | codedelta_server.py scan |
| What it is | Compiled C++ binary | Headless mode of the full app (Python) |
| Change measurement | yes | yes (runs the engine) |
| AI Audit (authorship) | no | yes |
| Agent Scan | no | yes |
| Runs on cron / CI | yes | yes |
| Needs the ML stack | no — lean | yes (bundled in the full app) |
The engine reaches into the Python world for exactly one thing: licence verification. The batch CLI, being part of the Python layer already, calls the engine for measurement and then adds the AI analysis on top.
How a run flows, step by step
Every invocation follows the same path. The licence is checked before any analysis begins — if it fails, the tool stops immediately and nothing is scanned.
A single command-line run, start to finish. The licence gate comes before any scanning.
What "analyse each pair" actually does
For every file that exists in both versions, the engine strips comments and whitespace down to logical lines, then performs a structural diff. This is why its change counts are meaningful: reformatting, re-indenting, or re-commenting code doesn't register as churn — only genuine logical change does. The result for each file is classified as changed, added, deleted, or unchanged, and the logical-line deltas (CHG / DEL / ADD) are summed into the project totals.
The licence gate
The engine is licensed software. It checks for a valid licence before doing any analysis, and refuses to run without one. This is true of the command-line engine itself — it is not a free-standing tool you can run unlicensed.
Activating a licence
Activation is a two-step exchange, done once per machine:
Licence activation — once per machine. The key is node-locked to the machine ID.
Licence types
| Type | What it is |
|---|---|
| Trial | Time-limited evaluation licence. |
| Personal | Single-user, host-locked to one machine. |
| Corporate | Organisation licence (generic timed / unlimited seats per terms). |
All types are time-bounded with start and end dates; they differ in scope and duration, and each key is validated cryptographically against the machine it was issued for.
"Can the engine be used on its own?" Yes — the command-line engine runs entirely standalone for measurement (no AI, no GUI needed). But not unlicensed: it verifies a valid licence first and exits with code 4 if none is found. Activate once with --activate, and thereafter it runs unattended — ideal for cron and CI.
What it produces
A single run can emit several artefacts at once — readable reports for people, structured data for tools, and a database for tracking change over time.
| Output | Flag | Purpose |
|---|---|---|
| HTML report | -o / --output | The main human-readable report. Two companions are written alongside it: *_overview.html (a PM-friendly summary) and *_diff.html (a side-by-side diff viewer). |
| CSV export | --csv | Per-file metrics as comma-separated values — for spreadsheets and pipelines. |
| XML export | --xml | Per-file metrics as XML, in an EPM-compatible format. |
| Trend database | -d / --db | A SQLite database that appends each run (never overwrites) — the basis for longitudinal trending across many runs over time. |
Progress and result text goes to the error stream (stderr); the output stream (stdout) is reserved for machine-readable output. That separation is deliberate — it lets a script capture clean data while a human still sees progress.
Every option, in one place
| Option | What it does |
|---|---|
| <old_dir> <new_dir> | Required. The two source trees to compare (old first, then new). |
| -o, --output | HTML report path (default codedelta_report.html). |
| --csv / --xml | Also write a CSV / XML export. |
| -d, --db | SQLite DB for trending (default codedelta.db; appends). |
| --project | Project name (default: the new directory's name). |
| --old-label / --new-label | Labels for each version (e.g. a version number, git hash, or date). |
| --note | Free-text note recorded with the run (e.g. 'nightly cron'). |
| --exclude | Comma-separated directories to skip. |
| --snapshot-date | Assign a date (YYYY-MM-DD) to the run. |
| --metric-set | Restrict to specific metric codes (default: all). |
| --ext | Extension→language overrides (e.g. h2=cpp,inc=php). |
| --threshold-churn N | Exit with code 3 if total churn (CRN_LLOC) exceeds N — for failing CI builds. |
| -v / -q | Verbose (every file) / quiet (errors only — for cron). Mutually exclusive. |
| --machine-id / --activate | Licensing: print the machine ID / activate a key. |
| -h / -V | Help / version. |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | Generic failure (I/O error, missing directory, report write failed). |
| 2 | Invalid arguments. |
| 3 | --threshold-churn exceeded (used to fail a build deliberately). |
| 4 | No valid licence. |
The batch CLI — AI from the command line
Everything above describes the engine. The batch CLI is the second command-line tool: a headless command that runs the full analysis — change measurement, AI Audit, and Agent Scan — with no graphical interface. This is how you invoke AI from a terminal or a scheduled job.
Pick exactly what runs — --mode
You don't have to run everything. The --mode flag selects any single analysis or combination:
| --mode | Runs |
|---|---|
| churn | Change measurement only (engine). Fast — no AI. Needs two dirs. |
| ai | AI Audit only (authorship: GSS / MLS / AIC). |
| agent | Agent Scan only (code that calls / launches AI). |
| both | AI Audit + Agent Scan. |
| ai_audit | Everything: churn + AI Audit + Agent Scan. |
Default: with two directories it runs everything (ai_audit); with one directory it runs both (audit + agent). A live progress counter shows in every mode.
Raw output for pipelines
The batch CLI writes the AI results as raw data, not just HTML — so a dashboard, spreadsheet, or script can consume them:
Output flags: --html (reports), --csv / --json (raw per-file scores), --xml (engine EPM export), --db (trend database). If none are given, all are produced.
Alerting for cron / CI
Like the engine, it can signal a pipeline through its exit code — opt-in:
--fail-on-critical— exit non-zero if any file is a CRITICAL agent risk.--fail-on-ai N— exit non-zero if the AI-written percentage reaches N.- Otherwise it exits 0 unless it crashes — safe for "just archive the report" cron jobs.
The engine is the fast, lean, measurement-only command-line tool. The batch CLI is the full command-line tool — same measurement plus AI Audit and Agent Scan, with raw data output and cron-friendly exit codes. Both run headless and unattended; you choose by which capability you need.
Running it on a schedule (cron / CI)
The engine is built to run unattended. --quiet keeps logs clean, the appending database builds a history, and the exit codes let a pipeline react automatically.
A weekly cron run with trending
A CI build gate
The examples above use the engine (measurement only). To run the AI Audit or Agent Scan on a schedule, use the batch CLI instead — e.g. python3 codedelta_server.py scan ./src --mode both --quiet --fail-on-critical. Same unattended operation, with AI analysis included. See The batch CLI.
CodeDelta gives you two command-line tools. The engine is a licensed, self-contained C++ tool that compares two versions of a codebase and reports exactly what logically changed — HTML for people, CSV/XML for tools, a SQLite trend database over time; fast, lean, measurement only. The batch CLI is the headless full tool: the same measurement plus the AI Audit and Agent Scan, with raw data output and cron-friendly exit codes — this is how AI analysis runs from the command line. Both check a licence first, both run unattended on a schedule. You pick by capability: change metrics and CI gating → engine; AI authorship and agent-code detection → batch CLI.
Quick-start guide
From zero to your first report in four steps.
Step 1 — Activate your licence (once per machine)
Step 2 — Run your first comparison
Point it at two versions of your code — the old one first, the new one second:
Step 3 — Open the report
Open report.html in any browser. Two companion files are written next to it automatically:
report_overview.html— a manager-friendly summary of the headline numbers.report_diff.html— a side-by-side viewer to see the actual changed lines.
Step 4 — Add raw data if you need it
Ask for CSV and/or XML alongside the HTML, plus a database to track change over time:
Everything else is refinement — labels for your versions (--project, --new-label), a churn limit to fail CI builds (--threshold-churn), or --quiet for scheduled runs. See Every option for the full list.
FAQ
Using it
Do I have to give it two folders?
Yes — the engine measures change between two versions, so it needs an old tree and a new tree. It's a comparison tool, not a single-snapshot counter. (The full application's AI features can analyse a single snapshot; the command-line engine compares two.)
What does it count as a "change"?
Logical change only. It strips comments and formatting down to logical lines (LLOC) before diffing, so re-indenting, reformatting, or re-commenting code does not show up as churn — only genuine changes to the code's logic do.
What's the difference between SLOC and LLOC?
SLOC is source lines of code (physical lines). LLOC is logical lines — the actual statements, independent of formatting. LLOC is the primary, more meaningful measure; SLOC is reported alongside it.
Where does the output go?
Wherever you point -o, --csv, --xml, and -d. Progress messages go to the error stream so they don't pollute captured data; structured output goes where you specify.
Can I run it automatically on a schedule?
Yes — that's a core use case. Use --quiet for clean logs, -d for a database that builds history across runs, and --threshold-churn N to make a CI build fail when churn is too high. See Running it on a schedule.
Does it need Python installed?
The measurement is pure C++ and self-contained. The one exception is licence verification, which uses a small verifier — in the full bundled application this verifier ships with it, so nothing extra is needed. The standalone bare engine binary relies on a system Python being present for that licence step.
AI features
Why doesn't the engine do AI detection?
The engine is the measurement layer — change metrics, churn, diffs — kept deliberately lean and dependency-free for fast measurement and CI gating. The AI features live in the Python layer. But you're not limited to the GUI for AI: the batch CLI (codedelta_server.py scan) runs the AI Audit and Agent Scan from the command line too. So "command line" doesn't mean "no AI" — it depends which of the two tools you run.
How do I get the AI analysis on the command line then?
Use the batch CLI — python3 codedelta_server.py scan … — the second command-line tool. It runs the AI Audit and Agent Scan (and can run the churn measurement too) entirely headless, with --mode to pick what runs and --json/--csv for raw output. So AI absolutely can be invoked from the command line; it's just a different command than the bare engine. See The batch CLI.
Licence & value
Can I run the engine without a licence?
No. It verifies a valid licence before doing any work and exits with code 4 if none is found. Activate once with --activate and it then runs unattended.
Is the licence tied to one machine?
Keys are node-locked: you send your machine ID (--machine-id) when ordering, and the key you receive is bound to that machine. Personal licences are single-machine; corporate licensing covers an organisation per its terms.
What licence types are there?
Trial (time-limited evaluation), Personal (single-user, host-locked), and Corporate (organisation). All are time-bounded with start and end dates.
What do the exit codes mean for my scripts?
0 success · 1 generic failure · 2 bad arguments · 3 churn threshold exceeded (a deliberate build-fail signal) · 4 no valid licence. Scripts and CI pipelines branch on these.
Is my source code sent anywhere?
The command-line engine's measurement runs locally on your machine — it reads your files and writes reports locally. (Licence keys are validated cryptographically against your machine, not by phoning home for each run.)