Configuration Schema Reference
Complete reference for all Karandash configuration options.
Karandash supports three configuration formats: Kotlin DSL (.karandash/config.kts), YAML (.karandash/config.yaml), and JSON (.karandash/config.json). The Kotlin DSL is the primary format. YAML and JSON equivalents are shown where applicable.
Top-Level Structure
| Block | Type | Required | Description |
|---|---|---|---|
extends |
string, object, or array | No | Config inheritance (see Config Inheritance) |
rules |
object | No | Validation rules configuration |
policies |
array | No | Conditional overrides applied when a when: expression matches (see Policies) |
platforms |
object | No | Platform configuration with inline authentication |
reporters |
object | No | Output and reporting configuration |
plugins |
object | No | Plugin management settings |
scripts |
array | No | Custom JavaScript validation scripts: a list of entries with path, optional mode, timeout and env (allowed env var names) (see Scripts) |
ai |
object | No | AI-powered analysis and enrichment settings |
auth |
object | No | Named credentials for remote extends: parents and { file: } references. Merged per entry name through extends: (a child entry replaces only the fields it sets) |
env |
object | No | Default values for ${VAR} interpolation, used when the variable is unset. Denylisted variables stay unset |
profile |
string or object | No | Profile to apply (see Profiles) |
profile-overrides |
object | No | Threshold overrides merged into rule configs after profile resolution |
severity-cap |
string | No | Shadow mode: findings more severe than this severity (error, warning or info) are lowered to it; rules.<id>.severity-cap caps one rule (see YAML config) |
patterns |
object | No | User-defined named patterns, used in rule patterns as @name (see Patterns) |
baseline |
string | No | Fingerprint file of findings that are not reported; the --baseline flag wins. --update-baseline rewrites it and needs a path from the flag or this key |
dangerfile |
string | No | Path to a Dangerfile.js or Dangerfile.df.kts run as part of validation (see Dangerfile) |
auto-approve |
object | No | Approve the MR when findings stay below a severity threshold |
enrichment |
object | No | Pre-validation enrichment stage and provider configs (see Enrichment) |
rule-enrichment |
object | No | Per-rule enrichment bindings: rule ID to enrich: list of enrichment IDs or globs |
cache |
object | No | Cache settings (see Cache) |
timeouts |
object | No | Timeout settings |
http |
object | No | HTTP client settings (retry, pagination, response cache) |
limits |
object | No | Safety limits for expressions, extends:, globs, regexes and patterns (see Limits) |
display |
object | No | Display preferences (git SHA length, watcher debounce, console marks) |
report |
object | No | Report preferences: language (BCP-47 tag, default en) for AI messages, the markdown summary and inline-review lines (strings in English, other languages from a translation pack, Russian and Polish built in; ai.response-language is its alias, see Report language); transparency (summary: off\|collapsed\|expanded, inline-why, flow-diagram) walkthrough (off\|collapsed) and style (quiet\|standard\|verbose, default standard; see Report style) (see Report transparency) |
security |
object | No | Network security: blocked-hosts (extra hostnames every outbound URL check refuses, see Security) |
diagnostics |
object | No | Runtime diagnostics (memory and CPU monitoring) |
dry-run |
boolean | No | Default false. Sets the is_dry_run condition; with dry-run-scope it also suppresses work (see Dry run) |
dry-run-scope |
string | No | ai or all: what dry-run: true suppresses. Unset suppresses nothing |
options |
block | No | Kotlin DSL only: the keys inside options { } are read as top-level keys. YAML and JSON write them at the top level |
$schema |
string | No | JSON Schema URL for editors. Not read by Karandash |
version |
string or number | No | Config schema version (major.minor, currently 1.0; init writes it). A version newer than the running karandash supports fails the load naming the upgrade; an equal or lower one is accepted. A non-numeric value fails the load |
allow-private-network (allow_private_network, allowPrivateNetwork) |
boolean | No | Default false. Allows private and dotless hosts for outbound URLs (self-hosted services on an internal network); cloud-metadata, link-local and loopback hosts stay blocked and scheme rules are unchanged (configured URLs must be HTTPS; redirects to http:// on a permitted host are followed). An extends: parent's value applies to the run like the root's own (a root false overrides it); while the extends: chain is fetched, a parent's value applies to fetching its own parents unless a layer closer to the root sets it. Applies to the whole run. See Network access |
allow-localhost (allow_localhost, allowLocalhost) |
boolean | No | Default false. Disables all SSRF checks (loopback, private, HTTP); local development only. Inherits through extends:: a parent's value applies to the run and to fetching its own parents |
Keys may be written in kebab-case, snake_case or camelCase. Any other top-level key gives an unknown-key warning (E0007), unless a loaded plugin reads it.
Platform credentials are configured inline within the platforms: block. The top-level auth: block holds credentials for fetching config files (remote extends: parents, { file: } references), not for the platform API.
karandash {
rules { /* ... */ }
platforms { /* ... */ } // Authentication configured here
reporters { /* ... */ }
plugins { /* ... */ }
scripts { /* ... */ }
ai { /* ... */ } // AI rules and enrichment
}
AI Keys
Keys of the ai: block, in any spelling (kebab-case, snake_case, camelCase). An object-valued key not listed here is
read as a per-analyzer block (<analyzer-id> row).
| Key | Type | Description |
|---|---|---|
enabled |
bool | Default true. false turns AI off: the block is ignored, so no AI rules, provider checks, AI state or AI findings |
provider |
string | Default LLM provider (default openai) |
api-key |
string | Provider API key; prefer ${ENV_VAR} interpolation |
base-url |
string | Provider endpoint override (self-hosted or proxy) |
model |
string | Default model; unset uses the provider's default |
model-fallback |
list | Models tried in order when the primary model fails |
models |
object | Per-analyzer model, analyzer ID to model |
temperatures |
object | Per-analyzer temperature (0.0-2.0) |
providers |
object | Per-provider settings, provider ID to its block |
rule-providers |
object | Per-analyzer provider, analyzer ID to provider ID |
features |
object | Analyzer on/off switches, analyzer ID to boolean (same as ai.<analyzer-id>.enabled) |
timeout |
duration | Provider request timeout; a bare number is seconds |
max-retries |
int | Retries of a failed provider call after the first attempt (default 2; 0 = one attempt) |
ollama |
object | allow-hosts: hosts the ollama provider may reach besides loopback, private-network and single-label ones, matched by name (default [host.docker.internal]; a set list replaces it) |
execution-timeout |
duration | Wall-clock cap for the whole AI stage |
concurrency |
int | Concurrent LLM calls (default 20) |
fail-on-error |
bool | Default false. Fail the run when an AI call fails instead of logging and continuing |
dry-run |
bool | Default false. Build prompts without calling the provider |
strictness |
string | Review strictness preset (default standard) |
review-mode |
string | Which diff lines are reviewed (default changed) |
context-lines |
int | Diff context lines fetched around each hunk |
best-practices |
string or { file: } |
Project best practices added to every prompt |
extra-instructions |
string or { file: } |
Extra instructions added to every prompt |
prompts |
object | Prompt overrides per analyzer |
prompt-overrides |
object | Prompt text overrides, prompt ID to text |
system-prompts |
object | System prompt overrides per analyzer |
context |
object | Named context strings added to prompts |
finding-template |
string | Template for AI finding messages |
reasoning |
string | Reasoning style (default direct); per analyzer via ai.<analyzer-id>.reasoning |
reasonings |
object | Per-analyzer reasoning, analyzer ID to style (same as ai.<analyzer-id>.reasoning) |
analyzerMaxTokens |
object | Per-analyzer token budget, analyzer ID to tokens (same as ai.<analyzer-id>.max-tokens; default: the analyzer's estimate) |
structured-output |
bool | Default true. Constrain analyzer replies to their result schema where the provider supports it; per analyzer via ai.<analyzer-id>.structuredOutput |
structuredOutputs |
object | Per-analyzer structured output, analyzer ID to bool (same as ai.<analyzer-id>.structuredOutput) |
prompt-cache-ttl |
string | Anthropic prompt-cache lifetime, 5m (default) or 1h |
reasoning-effort |
string | Unset by default. OpenAI-compatible providers send it as OpenRouter reasoning: {effort} (none, minimal, low, medium, high); lower it when a reasoning model spends the whole output cap on hidden reasoning and returns no content |
shared-system-prompt |
bool | Default false. One common system prompt for every analyzer; each analyzer's instructions move after the shared MR context so the cached prefix is shared across analyzers |
stream |
bool | Default false. Stream completions (SSE / NDJSON) so long generations are guarded by an idle timeout; text and usage match the non-stream result |
stub |
object | Options of provider: stub: replyFile, one reply or a JSON map by model / system-prompt key / default; no network, usage 0 |
max-token-budget |
int | Token budget per run (default 50000). With large-mr.scale-budget (default) it only seeds each rule's starting share: how much an MR gets reviewed is set by cost-budget, and the plan's [ai] budget plan line names the value that covers the whole MR |
context |
object | budget: input tokens one AI request may use, auto (default: a quarter of the model window, at most 64000, within the cost cap) or a count; see Context budget; also stripImports and importGraph (booleans, default true, see AI review precision) |
budget |
object | max-input-tokens: optional ceiling over context.budget; reserve-output-tokens: output tokens every call keeps free (default 2000 when unset or 0); context tier weights |
cost-budget |
object | Per-run token cap (max-tokens-per-run, default 50000 even in a block that sets only max-cost-per-run-usd) and USD cap; with scale-budget it bounds the per-MR growth (a run budget above it is cut to it, with a warning); without it the run grows to every rule's need |
pricing |
object | Model ID (or prefix) to USD per million tokens, overriding the built-in prices |
limits |
object | Diff size, chunking and per-analyzer limits. reviewThreadAnalysisMaxTokens, designDocDriftMaxTokens, generateDescriptionMaxTokens, mrSummaryMaxTokens, prSplitMaxTokens and outdatedDocsMaxTokens cap those analyzers' replies; unset, they fall back to descriptionMaxTokens (review-thread analysis) or reviewMaxTokens (the others), which warns once |
thresholds |
object | Per-analyzer score thresholds |
max-comments |
int | Soft cap on review comments per MR (default 10): repeats collapse first, then the rest rank by severity, category and confidence; BUG/SEC/DATA/LEAK comments are never cut by it |
max-comments-hard |
int | Optional hard cap on review comments per MR, every category included (the worst and surest kept); unset by default, so there is no hard cap |
split-threshold |
int | Change count above which an MR split is suggested |
code-quality-include-maturity-level |
bool | Add the maturity level to the code-quality report |
size-policy |
object | Skip, exclude and partial-review policies for large MRs |
chunking |
object | Chunk size, overlap and pass count (max-chunks, default 10, same as limits.maxChunks) for large diffs; unset uses ai.limits. chunk-size is a ceiling: the chunk is what one call holds (large-mr.max-call-tokens with large-mr.scale-budget, else its share at most that; at most the model context; less the prompt and output reserve, half of it with large-mr.chunk-context) at the diff's own characters per token; a larger chunk-size is capped there with a warning, a chunk still over it (one huge hunk) is skipped and reported, never cut |
incremental |
object | enabled: false reviews the whole diff on every run instead of only the delta |
large-mr |
object | Oversized-MR threshold, chunk parallelism and incremental override (see ai.large-mr) |
filters |
list | File globs the AI review is limited to |
rule-filters |
object | Per-analyzer file globs |
filter |
object | Post-processing filter for AI findings |
mode |
string | Default analyzer mode |
priority |
string | Accepted, no effect; rank analyzers with ai.<analyzer-id>.priority (integer) |
priorities |
object | Analyzer or rule ID to integer rank for the token budget; higher is funded first, ai.<analyzer-id>.priority wins on conflict |
concern-area |
string | Default analyzer concern area |
rules |
object | Per-rule AI strategy, rule ID to strategy block |
hooks |
object | Hook name to { action } (log, ...) |
scopes |
object or list | Path-scoped prompt overlays (see AI Scopes) |
review |
object | Path-scoped project review instructions, sent when their paths match |
learnings |
object | The calibrate --learn file read from the MR base (see ai.learnings) |
thread-commands |
object | Which @karandash thread commands are answered (see ai.thread-commands) |
checks |
list | Pre-merge checks answered pass, fail or n/a and shown as a checklist (see ai.checks) |
checks-ticket-compliance |
bool | Default false. Add a checklist row per acceptance criterion of the linked ticket |
enrichment |
object | Pre-validation title and description generation (see AI Enrichment) |
enricher |
object | Knowledge-context enricher settings |
grounding |
object | Grounding of findings in the diff; windowLines, negatedClaims, evidenceCheck and miss are in AI review precision |
reviewSampling |
object | ai.review-comments.samples (default 2) and ai.review-comments.sample-temperature (default 0.5); see AI review precision |
agreement |
object | How two review-comments samples are matched (see AI review precision) |
ranking |
object | Score weights and protect conditions of the finding caps (see AI review precision) |
dedup |
object | Cross-rule in-run dedup of AI findings (see AI review precision) |
hints |
object | Deterministic hint block of review-comments (see AI review precision) |
testGap |
object | level: mr (default) or file (see AI review precision) |
streamDeadline |
duration | Default 5m. Longest a streamed call may run in total before it is retried |
streamStall |
duration | Default 60s, at most ai.timeout. Longest silence between two chunks of a streamed call before it is retried. Not enforced by the macOS and Linux native builds: their curl HTTP engine has no idle timeout, so there streamDeadline bounds a silent stream |
constitution |
object | Project constitution checked by the AI review |
context-quality |
object | Smart truncation, related files, full-file context, convention detection, finding validator |
convention-context |
object | Convention detection context |
cross-file-context |
object | Add related repository files (imports, tests) to the prompt |
cross-file-context-max-chars |
int | Character cap for the cross-file context |
correlation |
object | Merge same-location findings across analyzers; compound-risk patterns |
contradictions |
object | Contradiction removal and how a contradictory pair is resolved |
custom-rules |
list | User-defined AI rules: id, name, prompt, severity, max-tokens, temperature, enabled, priority (integer rank in the scale-budget plan) |
gates |
list | Quality gates over AI findings |
enforcement-schedule |
list | Phased enforcement (warn, then error) by date |
severity-overrides |
list | Severity overrides for AI findings |
grace-periods |
list | Grace periods for rules |
grace-period |
object | Approval-gated grace window opened by a description tag |
conditional-sections |
list | Prompt sections added when a condition holds |
compositions |
list | Rules composed from other rules' findings |
seniority-tiers |
list | Author seniority tiers that adjust the review |
teams |
list | Team definitions for routing and notifications |
notifications |
list | Notification routes for AI findings |
tracks |
list | Branch-specific rule tracks |
environment-tracks |
list | Short form of tracks: { target-branch, rules } |
macros |
object | Short form of macro-definitions: macro name to a list of { rule, ...settings } |
macro-definitions |
object | Named rule-setting macros |
apply-macros |
list | Short form of macro-references: macro names applied to all files |
macro-references |
list | Macros applied by file glob |
adrs |
list | Architecture decision records checked as constraints |
canary |
object | Canary rollout per rule |
violation-budgets |
list | Tolerated finding counts per rule |
violation-budget |
object | Per-file baseline of tolerated findings |
execution-profile |
string | Name of the execution profile to apply |
execution-profiles |
object | Named execution profiles |
consensus-models |
list | Two or more: each custom AI rule runs once per model and keeps the findings enough models report |
consensus-strategy |
string | Default intersection (every model must report the finding); majority (more than half), first_agreement (any two) |
analyzer-consensus |
bool | Default false. Also vote on built-in analyzers that review the diff; MR-level ones (summary, risk score) ask one model |
consensus |
object | models and strategy, same as consensus-models and consensus-strategy (the long form wins when both are set) |
feedback |
object | Feedback store settings (enabled, skip-repeat-finding-types, reply-judge) |
feedback-enabled |
bool | Same as feedback.enabled |
feedback-skip-repeat-finding-types |
bool | Same as feedback.skip-repeat-finding-types: skip a rule once its findings were dismissed repeatedly |
feedback-reply-judge |
string | Same as feedback.reply-judge: off (default) or llm asks the model about replies the keyword classifier leaves unknown (at most 50 calls per run, not in a dry run) |
pgo-enabled |
bool | Default false. Profile-guided ordering of analyzers |
analyzer |
object | Analyzer settings |
defect-predictor |
object | Defect predictor settings |
pipeline |
object | AI pipeline thresholds, clone detection and reports |
statistics |
object | Statistics history settings |
research |
object | Research mode settings |
debug |
object | prompt: artifact dumps each sent request to files |
process-risk |
object | Score process risk and report it as an INFO finding |
routing |
object | Cheap-model triage, escalating to the strong tier by process risk |
inline-overrides |
object | @karandash override <rule>: <reason> description tags |
temporal |
object | Cross-MR repeat-violation escalation |
calibration |
object | End-of-run rule calibration report from the statistics history |
sandbox |
object | karandash test-rule defaults |
clone-detection |
object | Clone detection settings for the metrics enricher |
naturalness |
object | Naturalness metrics for the metrics enricher |
architecture |
object | Architecture checks of the pipeline extension |
dependencies |
object | Dependency checks of the pipeline extension |
mutation-testing |
object | Mutation testing settings |
response-language |
string | Alias of report.language |
<analyzer-id> |
object | Per-analyzer block: enabled, model, temperature, reasoning, mode, priority (integer rank in the scale-budget plan, higher funded first), concern-area, min-severity; other keys warn as unsupported |
AI review precision
| Key | Type | Default | Description |
|---|---|---|---|
review-comments.samples |
int | 2 |
Calls per review-comments chunk, 1 to 3. Extra samples run after every first call on a budget of their own (the rule's grant per sample), so they never cut coverage; measured cost about +45% per MR, most of the sample-2 prompt read from the provider prefix cache; 1 restores a single call |
review-comments.sample-temperature |
number | 0.5 |
Temperature of samples 2 and later, 0 to 2 |
agreement.lineWindow |
int | 3 |
Largest line distance of a pair of findings from two samples |
agreement.minSimilarity |
number | 0.3 |
Overlap of the messages' words of 4+ letters a pair needs, 0 to 1 |
agreement.singleton |
string | demote |
A finding only one sample reported: demote (INFO), drop or keep; BUG/SEC are never dropped unless drop |
grounding.windowLines |
int | 40 |
A backticked name must appear within this many lines of the anchor (or in the file's diff) or the finding is demoted |
grounding.negatedClaims |
bool | true |
Refute "undefined / not found" claims about a name present in the MR |
grounding.evidenceCheck |
bool | true |
Refute a finding whose quoted evidence line is absent from the file; demote one not within 2 lines of the anchor |
grounding.miss |
string | demote |
demote or drop a finding that misses the local check; never a BUG/SEC/DATA/LEAK finding |
ranking.weights.agreed / grounded / security |
int | 2 / 1 / 1 |
Score weights the caps rank by |
ranking.protect |
list | [agreed, grounded] |
Conditions (agreed, grounded) a BUG/SEC/DATA/LEAK finding must all meet to be kept past maxComments; a finding without the metadata is neutral |
dedup.crossRule |
bool | true |
Merge similar findings of different AI rules in one file |
dedup.lineWindow |
int | 3 |
Line distance for that merge |
hints.enabled |
bool | true |
Send the deterministic moved/defined identifier hints to review-comments |
hints.maxTokens |
int | 400 |
Upper bound of the hint block |
testGap.level |
string | mr |
mr: a test anywhere in the MR means no test-gap line; file: per review unit |
A bad value is a ConfigParseException naming the key. ai.context.stripImports (default true) leaves import/package lines out of windowed file context and ai.context.importGraph (default true) adds the import graph to cross-file context.
ai.learnings
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
bool | true |
Read the learnings file from the MR base (target branch, never the head), send it as guidance and apply it to the findings |
file |
string | .karandash/learnings.yaml |
Path of the file calibrate --learn writes |
min-rejections |
int | 5 |
Rejected-finding floor calibrate --learn needs before it writes an entry |
ai.thread-commands
| Key | Type | Default | Description |
|---|---|---|---|
ask |
bool | false |
Answer @karandash ask <question> in a reply to a bot thread (one model call from the run's AI budget); off, it gets a short "disabled" reply. @karandash why needs no model and is always on with ai.feedback |
ai.large-mr
| Key | Type | Default | Description |
|---|---|---|---|
max-units |
int | 10 |
An MR with more review units (modules or directories) is oversized: the summary suggests splitting it and incremental applies |
max-parallel |
int | 4 |
Chunks of one rule sent at once; each call still takes a permit of ai.concurrency |
incremental |
bool | unset | For an oversized MR, overrides ai.incremental.enabled; unset follows it |
test-gaps |
bool | true |
The summary gets a test-gap line per unit that changed production code and no test |
chunk-context |
bool | true |
A chunked call gives half its diff room to context (cross-file, enricher blocks) instead of filling it with diff |
mr-map-max-files |
int | 50 |
Each chunk's call lists up to this many files other chunks carry (path, +/- lines), so the model does not report them missing; 0 sends no list |
max-call-tokens |
int | 16000 |
Most tokens one chunked AI call is sized to (prompt, output reserve and diff). With scale-budget every chunked call is this size, at most the model context; off, a rule's share at most this. Lower it to spend less per call, raise it for fewer, bigger calls; under 1 = default with a warning |
scale-budget |
bool | true |
Per-MR budget plan: a chunked rule gets one call per chunk, each max-call-tokens at most the model context, never the rule's smaller share (at least its prompt, output reserve and 500 diff tokens; skipped with a reason when the context cannot hold that), so a big diff goes in more calls, not a bigger one; a whole-MR rule gets its prompt, output reserve and the MR's diff, at most the model context; funded by priority, highest first (ai.<analyzer>.priority or a custom rule's priority; default review-comments 2, whole-MR rules 1, the rest 0), and when chunks still do not all fit, the chunks with the highest-scored files (truncation.priority weights, hotspot included) first (the run budget grows by the same tokens), capped by cost-budget.max-tokens-per-run and max-cost-per-run-usd; without cost-budget every rule is funded in full up to max-run-tokens; one line before any call ([ai] budget plan: N calls, T tokens, ..., INFO when every rule is funded, WARN with each short rule's funded % and the cost-budget or max-run-tokens value that covers the MR); false = every rule keeps one share |
max-run-tokens |
int | 500000 |
Without cost-budget, the most tokens scale-budget grows one MR's run to (never below the run budget already set); past it the lowest-priority rules are short and one warning says so; 0 = no cap |
Values under 1 for max-units, max-parallel or max-call-tokens warn and fall back to the default.
ai.checks
A list of pre-merge checks the model answers pass, fail or n/a for in one call, shown as a checklist.
| Key | Type | Default | Description |
|---|---|---|---|
name |
string | required | Row label in the checklist |
instruction |
string | required | What must hold for the check to pass |
paths |
list of globs | [] |
When set and no changed file matches, the check is n/a without asking the model |
mode |
warn or error |
warn |
error makes a failing check an ERROR finding (non-zero exit); warn a WARNING |
AI Enrichment
Pre-validation AI enrichment generates MR titles and descriptions before rules run. This is opt-in and configured under the ai: block.
YAML
ai:
provider: anthropic
model: claude-sonnet
enrichment:
generate-description: true
generate-title: true
skip-if-description-exists: true
JSON
{
"ai": {
"provider": "anthropic",
"model": "claude-sonnet",
"enrichment": {
"generate-description": true,
"generate-title": true,
"skip-if-description-exists": true
}
}
}
| Field | Type | Default | Description |
|---|---|---|---|
generate-description |
bool | false |
Generate MR description using AI |
generate-title |
bool | false |
Generate MR title using AI |
skip-if-description-exists |
bool | true |
Skip generation when description is already present |
model |
string | null |
Model for the description and title generation calls; unset uses the routed ai.model |
max-tokens |
int | 2000 |
Response token limit for the description and title generation calls |
Enrichment can also be triggered via CLI flags --enrich and --dry-run-enrich without config file changes.
AI Scopes
Path-based prompt overlays for monorepo and multi-stack projects. When an MR touches files matching a scope's patterns, that scope's instructions are added to the AI prompt. Multiple scopes can match simultaneously.
ai:
provider: anthropic
scopes:
android:
paths: ["android/**", "app/src/**/*.kt"]
instructions: |
Check Activity/Fragment lifecycle issues.
Flag missing null checks in Java interop.
best-practices: "Use ViewModel for UI state."
core:
paths: ["core/cpp/**", "**/*.cpp", "**/*.h"]
instructions: "Check memory safety and ABI compatibility."
best-practices: "Use RAII. Prefer std::unique_ptr."
| Field | Type | Required | Description |
|---|---|---|---|
paths |
list of strings | Yes | Glob patterns that trigger this scope |
instructions |
string | No | Scope-specific review instructions |
best-practices |
string | No | Scope-specific best practices |
When no scopes match, built-in language detection provides language-specific overlays as fallback. See AI Rules for details.
Extends
Config inheritance allows you to build on shared base configurations. See Config Inheritance for detailed documentation.
String Form
extends: "https://example.com/base-config.yaml"
Object Form (with Auth)
extends:
url: "https://private.gitlab.com/config.yaml"
auth:
type: bearer-token
token: "${GITLAB_TOKEN}"
Auth types: bearer-token, basic-auth, custom-header
Keys of an object entry (any spelling):
| Key | Type | Description |
|---|---|---|
url |
string | Remote URL, local path or @manifest reference. One of url or pattern is required |
pattern |
glob | Local glob expanding to several config files |
if |
expression | Condition; the entry is skipped when it is false. ${VAR} is resolved by the condition evaluator (unset compares as "") |
cache |
object | Cache settings of a remote parent (below) |
merge-strategy |
object | Field path to merge mode, overriding the default merge for that field |
file-resolution |
string | How { file: } references in a remote parent resolve: local (default), fallback-remote, fallback-local, strict |
auth |
object or string | Credentials for fetching this url (see below), or the name of an auth.<name> entry in the same file |
trust |
boolean | Lets { file: } values of this remote parent read local files outside the project root, absolute paths included (default false) |
| Key | Type | Description |
|---|---|---|
ttl |
string | Cache lifetime of a remote parent (seconds or duration, default 1h; 0s disables, -1/never caches forever) |
| Key | Type | Description |
|---|---|---|
type |
string | bearer-token, basic-auth or custom-header |
token |
string | bearer-token: the token |
username |
string | basic-auth: user name |
password |
string | basic-auth: password |
name |
string | custom-header: header name |
value |
string | custom-header: header value |
Array Form (Multiple Extends) - NEW
extends:
- "https://company.com/base.yaml"
- "https://company.com/security.yaml"
- url: "https://private.com/team.yaml"
auth:
type: bearer-token
token: "${TOKEN}"
Merge order: Left-to-right (element 0 is base, later elements override) Maximum: 10 entries (error E0014 if exceeded)
Merge Rules
- Objects merge deeply: the child's value wins key by key, and keys only the parent sets are inherited.
- Arrays are replaced: a child's
scripts,ai.gates,ai.customRules,ai.notifications,ai.tracksor any rule's list (for examplejiraTicket.projectKeys) replaces the parent's list as a whole; nothing is appended or merged by index. To extend a parent's list, repeat its items in the child. policiesis the exception: policies merge byname(or bywhenwhen unnamed). A child policy with the same name replaces the parent's; other policies from both are kept.
Auth
Named credentials (auth.<name>) for remote extends: parents (an entry written auth: <name>, which also takes the
auth's file-resolution as its default) and { file: } references, merged per entry name through extends:.
| Key | Type | Description |
|---|---|---|
type |
string | bearer-token, basic-auth or custom-header |
token |
string | bearer-token: the token |
username |
string | basic-auth: user name |
password |
string | basic-auth: password |
name |
string | custom-header: header name |
value |
string | custom-header: header value |
base-url |
string | Host (and port) this credential is keyed for; a content source on another host is refused. Unset: any host |
file-resolution |
string | Default file-resolution (local, fallback-remote, fallback-local, strict) of every extends: entry that names this auth and sets none of its own; an invalid value fails the load. Unset: local |
Report
| Key | Type | Default | Description |
|---|---|---|---|
language |
string | en |
Output language (BCP-47 tag, base subtag used) of AI messages, the markdown summary and inline-review lines; strings are English, other languages come from a translation pack (Russian and Polish built in), others render in English. ai.response-language is its alias |
transparency |
object | How the summary shows how the review was made (see below) | |
walkthrough |
off or collapsed |
off |
Whether the AI MR summary carries a changes walkthrough |
style |
quiet, standard or verbose |
standard |
Report layout preset for every format; verbose restores the previous layout, reporters.<format>.style overrides it per format (see Report style) |
| Key | Type | Default | Description |
|---|---|---|---|
summary |
off, collapsed or expanded |
collapsed |
The provenance block of the markdown summary |
inline-why |
bool | false |
Each inline note ends with a one-line "why" footer |
flow-diagram |
bool | false |
The block carries a Mermaid flow diagram of the run; the diagram is written to .karandash/debug/review-flow.md either way |
Security
| Key | Type | Default | Description |
|---|---|---|---|
blocked-hosts |
list of strings | [] |
Extra hostnames every outbound URL (webhooks, provider base URLs, redirects) is refused for, on top of the built-in metadata and link-local hosts; it only adds blocks, and allow-localhost never lifts them |
Cache
The cache: block. Durations take a unit (ms, s, m, h, d, w, mo, y; compounds like 1h 30m); sizes take b, kb,
mb, gb or tb. Commands: karandash cache.
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | true |
false keeps the caches memory-only, with no per-MR state store and no remote cache |
dir |
string | ~/.karandash/cache |
Cache base directory |
responses |
object | Provider API response cache (cache.responses below) |
|
downloads |
object | Remote extends: config cache (cache.downloads below) |
|
state |
object | Per-MR validation state: rule results, AI state (cache.state below) |
|
memory |
object | In-memory cache sizes (cache.memory below) |
|
remote |
object | none (local only) | Shared remote cache backend (cache.remote below) |
default-ttl |
duration | Provider response TTL when cache.responses.ttl is unset and there is no timeouts.cache-ttl |
|
max-cache-size |
integer (bytes) | unbounded | The end-of-run GC evicts the oldest entries, after expiry cleanup, until the namespaces the run used fit |
glob |
object | max-entries (default 1000): compiled glob cache size |
|
regex |
object | max-entries (default 1000): compiled regex cache size |
|
patterns |
object | max-entries (default 512): resolved named-pattern cache size |
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | true |
Cache provider responses, revalidating with ETags |
ttl |
duration | timeouts.cache-ttl, else cache.default-ttl, else 60s |
Response lifetime |
persist |
boolean | false |
Also keep responses on disk so a later run within ttl reuses them; off, they live in memory for one run |
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | true |
Cache remote extends: configs |
ttl |
duration | 1h |
Lifetime of a fetched config; an extends: entry's own cache.ttl wins. Merged through extends: (the closer layer wins) |
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | true |
Keep per-MR state between runs |
ttl |
duration | 7d |
State lifetime |
| Key | Type | Default | Description |
|---|---|---|---|
max-entries |
integer | 512 |
Default size of every in-memory cache |
overrides |
object | {} |
Per-cache size by cache name, e.g. responses: { max-entries: 256 }, glob-patterns: { max-entries: 1024 } |
| Key | Type | Default | Description |
|---|---|---|---|
backend |
string | required | http, s3 or gcs. gcs is the HTTP backend: point url at the bucket's HTTP endpoint and put the credential in auth |
url |
string | required | Backend base URL |
auth |
string | Authorization header for http/gcs: sent as is when it names a scheme (Basic …, Bearer …), otherwise as a bearer token. Never logged |
|
push |
boolean | true |
Upload new local entries |
pull |
boolean | true |
Read entries missing locally |
prefix |
string | "" |
Key prefix under url |
max-blob-size |
size | 10mb |
Blobs over this are neither pushed nor read |
push-timeout |
duration | 5s |
Per-upload timeout |
pull-timeout |
duration | 3s |
Per-download timeout |
include |
list of strings | [] |
Namespaces to share; empty shares every namespace except http-responses |
exclude |
list of strings | [] |
Namespaces never shared, applied after include |
region |
string | us-east-1 |
s3: signing region |
access-key-id |
string | s3: with secret-access-key, signs requests (SigV4) |
|
secret-access-key |
string | s3: see access-key-id |
|
session-token |
string | s3: temporary-credential token |
|
profile |
string | AWS_PROFILE, else default |
s3: shared-file profile when no keys are set; with no credentials found requests are anonymous |
ttl |
duration | cache gc --remote also expires local entries older than this, deleting their blobs locally and on the remote |
Rules
Universal Rule Options
Every rule block supports two optional fields that improve the developer experience when violations are found:
| Option | Type | Default | Description |
|---|---|---|---|
suggestion |
String |
null |
Short actionable hint shown to the MR author when this rule fails |
explanation |
String |
null |
Longer explanation of why the rule exists, shown with --explain |
These fields are available on all rules described below.
titleFormat
Validates MR/PR title format.
| Option | Type | Default | Description |
|---|---|---|---|
pattern |
String |
null |
Regex pattern the title must match (optional - falls back to structured type/scope/subject config, or skips pattern validation if neither is set) |
minLength |
Int |
10 |
Minimum title length |
maxLength |
Int |
null |
Maximum title length |
requireTicket |
Boolean |
false |
Require a ticket reference in the title |
suggestion |
String |
null |
Actionable hint shown when the rule fails |
explanation |
String |
null |
Explanation of why the rule exists (shown with --explain) |
Kotlin DSL:
rules {
titleFormat {
pattern = "^(feat|fix|docs|refactor|test|chore):"
minLength = 10
maxLength = 72
requireTicket = true
}
}
YAML:
rules:
titleFormat:
pattern: "^(feat|fix|docs|refactor|test|chore):"
minLength: 10
maxLength: 72
requireTicket: true
JSON:
{
"rules": {
"titleFormat": {
"pattern": "^(feat|fix|docs|refactor|test|chore):",
"minLength": 10,
"maxLength": 72,
"requireTicket": true
}
}
}
commitMessages
Validates commit message format.
| Option | Type | Default | Description |
|---|---|---|---|
format |
String |
null |
Preset format: "conventional" or custom |
pattern |
String |
null |
Custom regex pattern for commit messages |
maxLength |
Int |
null |
Maximum commit message length |
minLength |
Int |
null |
Minimum commit message length |
conventionalTypes |
List<String> |
null |
Custom list of conventional commit types (overrides the default list) |
rules {
commitMessages {
format = "conventional"
maxLength = 100
}
}
jiraTicket
Requires JIRA ticket references in the MR.
| Option | Type | Default | Description |
|---|---|---|---|
projectKeys |
List<String> |
[] |
JIRA project key prefixes (e.g., ["PROJ", "ENG"]). Effectively required for JIRA-family formats - validation emits an error finding if left empty |
pattern |
String |
null |
Custom regex pattern for ticket matching |
validateStatus |
List<String> |
null |
Allowed JIRA ticket statuses |
validateAssignee |
Boolean |
false |
Require the ticket to have an assignee |
rules {
jiraTicket {
projectKeys = listOf("PROJ", "ENG")
pattern = "[A-Z]+-\\d+"
}
}
branchNaming
Validates source and target branch naming conventions.
| Option | Type | Default | Description |
|---|---|---|---|
pattern |
String |
null |
Single regex pattern for branch names |
allowedPatterns |
List<String> |
[] |
List of allowed branch name patterns |
requireSourceMatch |
Boolean |
true |
Validate the source branch name |
requireTargetMatch |
Boolean |
false |
Validate the target branch name |
rules {
branchNaming {
allowedPatterns = listOf(
"feature/.*",
"bugfix/.*",
"hotfix/.*",
"release/.*"
)
requireSourceMatch = true
requireTargetMatch = false
}
}
fileChanges
Enforces rules based on which files are modified.
| Option | Type | Default | Description |
|---|---|---|---|
patterns |
List<FilePatternRule> |
[] |
File pattern rules (each with a glob pattern plus optional overrides) |
requireApproval |
List<String> |
null |
Usernames required to approve when matched files change |
requireLabels |
List<String> |
null |
Labels required when matched files change |
blockOnDraft |
fail \| warn \| off |
off |
Finding when the MR is a draft and matched files change |
Each pattern entry creates a FilePatternRule:
| Field | Type | Default | Description |
|---|---|---|---|
pattern |
String |
required | Glob pattern (e.g., "**/migrations/**") |
requireApproval |
List<String> |
null |
Override: users who must approve |
requireLabels |
List<String> |
null |
Override: labels required |
blockOnDraft |
fail \| warn \| off |
off |
Per-pattern finding on draft (used when the top-level key is off) |
rules {
fileChanges {
patterns = listOf(
FilePatternRule(pattern = "**/migrations/**", requireApproval = listOf("dba-team")),
FilePatternRule(pattern = "**/config/**", requireLabels = listOf("database")),
)
}
}
codeowners
Enforces CODEOWNERS file approval requirements.
| Option | Type | Default | Description |
|---|---|---|---|
path |
String |
"CODEOWNERS" |
Path to the CODEOWNERS file |
requireOwnerApproval |
Boolean |
true |
Require approval from code owners |
rules {
codeowners {
path = ".github/CODEOWNERS"
requireOwnerApproval = true
}
}
approval
Controls approval requirements.
| Option | Type | Default | Description |
|---|---|---|---|
minApprovals |
Int |
1 |
Minimum number of approvals required |
requiredApprovers |
List<String> |
[] |
Specific users who must approve |
noChangesSinceApproval |
Boolean |
false |
Same as freshApprovals: invalidate approvals if new commits are pushed. |
rules {
approval {
minApprovals = 2
requiredApprovers = listOf("tech-lead", "security-team")
noChangesSinceApproval = true
}
}
reviewer
Controls reviewer assignment requirements.
| Option | Type | Default | Description |
|---|---|---|---|
requiredReviewers |
List<String> |
[] |
Users who must be assigned as reviewers |
requiredTeams |
List<String> |
[] |
Teams that must have a reviewer assigned |
excludedReviewers |
List<String> |
[] |
Users who cannot be reviewers (e.g., the MR author) |
rules {
reviewer {
requiredTeams = listOf("backend-team")
excludedReviewers = listOf("bot-user")
}
}
cicdStatus
Validates CI/CD pipeline status.
| Option | Type | Default | Description |
|---|---|---|---|
requirePassed |
Boolean |
true |
Require the pipeline to have passed |
requiredJobs |
List<String> |
[] |
Specific job names that must pass |
blockOnFailing |
fail \| warn \| off |
fail |
Severity of pipeline/required-job failures (warn skips the failing-only check, off reports none) |
rules {
cicdStatus {
requirePassed = true
requiredJobs = listOf("build", "test", "lint")
blockOnFailing = "fail"
}
}
conflict
Detects merge conflicts.
| Option | Type | Default | Description |
|---|---|---|---|
blockOnConflicts |
fail \| warn \| off |
fail |
Finding when conflicts are detected |
rules {
conflict {
blockOnConflicts = "fail"
}
}
draftPrevention
Detects draft/WIP merge requests. draft is accepted as an alias for the rule ID.
| Option | Type | Default | Description |
|---|---|---|---|
blockDraft |
fail \| warn \| off |
fail |
Finding when the MR is a draft |
wipPatterns |
List<String> |
["\\bWIP\\b", "\\[WIP\\]", "\\bwip:", "\\bWIP:"] |
Regex patterns that indicate WIP in the title |
rules {
draftPrevention {
blockDraft = "fail"
wipPatterns = listOf("WIP", "\\[WIP\\]", "DO NOT MERGE")
}
}
labels
Validates MR labels.
| Option | Type | Default | Description |
|---|---|---|---|
requiredLabels |
List<String> |
[] |
Labels that must be present |
forbiddenLabels |
List<String> |
[] |
Labels that must not be present |
conditionalLabels |
List<ConditionalLabel> |
[] |
Conditional label rules |
ConditionalLabel:
| Field | Type | Description |
|---|---|---|
condition |
LabelCondition |
Condition to evaluate |
requiredLabels |
List<String> |
Labels required if condition is true |
forbiddenLabels |
List<String> |
Labels forbidden if condition is true |
LabelCondition:
| Field | Type | Description |
|---|---|---|
hasLabel |
String |
True if MR has this label |
hasAnyLabel |
List<String> |
True if MR has any of these labels |
hasAllLabels |
List<String> |
True if MR has all of these labels |
rules {
labels {
requiredLabels = listOf("type/bug", "priority/high")
forbiddenLabels = listOf("do-not-merge")
}
}
sizeLimits
Limits MR size to encourage smaller, reviewable changes.
| Option | Type | Default | Description |
|---|---|---|---|
maxFiles |
Int |
null |
Maximum number of changed files |
maxLines |
Int |
500 |
Maximum number of changed lines |
maxCommits |
Int |
20 |
Maximum number of commits |
rules {
sizeLimits {
maxFiles = 20
maxLines = 500
maxCommits = 10
}
}
security
Scans for secrets and sensitive file changes.
| Option | Type | Default | Description |
|---|---|---|---|
scanForSecrets |
Boolean |
true |
Enable secret scanning in diffs |
secretPatterns |
List<String> |
(see below) | Regex patterns for secret detection |
sensitiveFiles |
List<String> |
(see below) | Glob patterns for sensitive files |
Default secret patterns detect: API keys, secret keys, passwords, access tokens, bearer tokens, AWS credentials, private keys, GitHub tokens, and GitLab tokens.
Default sensitive file patterns: .env, .env.*, config/secrets.yml, config/credentials.yml, *secret*, *credential*, *.pem, *.key, *.p12, *.pfx, id_rsa, id_dsa.
rules {
security {
scanForSecrets = true
sensitiveFiles = listOf("**/.env", "**/*.pem")
}
}
Policies
Top-level policies: array. Each entry has a when: condition expression; when it evaluates to
true for the current MR, the policy toggles modules, deep-merges config overrides into them,
overrides severity, and gates pipeline stages. Policies never add rules - they modify rules that
are already configured.
| Option | Type | Default | Description |
|---|---|---|---|
when |
String |
required | Condition expression, e.g. target_branch_matches("^main$") |
name |
String |
null |
Human-readable label used in logs |
modules |
List<String> |
(all) | Module IDs the policy applies to |
enabled |
Boolean |
null |
Enable/disable the scoped modules |
severity |
String |
null |
Override finding severity |
override |
object | {} |
Per-module config deep-merged into the scoped modules |
autoApprove / autoFix / scripts / dangerfile |
Boolean |
null |
Gate the corresponding pipeline stage |
Conditions are boolean expressions over predicates such as is_draft, label_exists("name"),
file_path_matches("glob"), target_branch_matches("regex"), and change_count > N, combined with
&&, ||, !, and parentheses. Full predicate reference:
Condition expression predicates.
policies:
- when: 'file_path_matches("**/migrations/**")'
modules: [approval, labels]
override:
approval:
minApprovals: 2
policies {
migrations {
when = "file_path_matches(\"**/migrations/**\")"
modules(listOf("approval", "labels"))
override {
approval { minApprovals = 2 }
}
}
}
See Conditional Rules (Policies) for evaluation semantics and per-rule
when: blocks.
Reporters
Each reporter is a combination of a FormatModule (renders output) and an OutputModule (delivers it). See Reporters for full documentation on each reporter.
| Option | Type | Default | Description |
|---|---|---|---|
console |
Boolean or object |
true |
Console output (ConsoleFormatModule + StdoutOutputModule) |
markdown |
Boolean or object |
auto | MR/PR comment (MarkdownFormatModule + PlatformOutputModule). |
json |
Boolean |
false |
JSON output (JsonReportFormatModule + StdoutOutputModule / FilesystemOutputModule) |
sarif |
Boolean or object |
false |
SARIF 2.1.0 (SarifFormatModule + StdoutOutputModule / FilesystemOutputModule) |
junit |
Boolean |
false |
JUnit XML (JunitFormatModule + FilesystemOutputModule) |
reviewdog |
Boolean |
false |
Reviewdog rdjson/rdjsonl (RdjsonFormatModule / RdjsonlFormatModule + StdoutOutputModule / FilesystemOutputModule) |
slack |
object | null |
Slack Block Kit (SlackFormatModule + SlackOutputModule) |
webhook |
object | null |
HTTP POST (JsonReportFormatModule + WebhookOutputModule) |
email |
object | null |
SMTP email (HtmlFormatModule + EmailOutputModule) |
html |
Boolean |
false |
HTML report (HtmlFormatModule + FilesystemOutputModule) |
codequality |
Boolean or object |
false |
GitLab Code Quality JSON (CodeQualityFormatModule); write it to a file with output: gl-code-quality-report.json |
status |
object | null |
The verdict as the platform's result status (RdjsonlFormatModule + StatusOutputModule): GitHub check run, GitLab commit status, Bitbucket Code Insights report, Azure DevOps PR status |
platform |
object | auto | Options of the MR comment output; comments: all\|summary\|inline\|none (default all) picks which comments are posted |
reporters.sarif
| Option | Type | Default | Description |
|---|---|---|---|
version |
String |
Karandash version | Override the tool version in the SARIF driver.version field |
reporters.slack
| Option | Type | Default | Description |
|---|---|---|---|
webhook |
String |
required without token |
Slack incoming webhook URL (must start with https://hooks.slack.com/) |
channel |
String |
null |
Slack channel override; required with token (a channel ID such as C0123456789) |
token |
String |
null |
Bot token (xoxb-…, scopes chat:write and channels:history). Set, it posts with chat.postMessage and a later run for the same MR updates that message with chat.update; the webhook is not used |
notificationTarget |
String |
set by the CLI | The MR this run is for (<project>!<mr>), used to find the earlier message; leave it unset |
reporters.status
| Option | Type | Default | Description |
|---|---|---|---|
name |
String |
karandash |
Name of the check run, commit status context, Code Insights report or PR status context |
detailsUrl |
String |
null |
Link shown with the status, e.g. the CI job URL |
onError |
warn or fail |
warn |
fail fails the run when the status cannot be published |
notificationState |
object | set by the CLI | This run's verdict; leave it unset |
reporters.webhook
| Option | Type | Default | Description |
|---|---|---|---|
url |
String |
required | HTTPS URL to POST results to |
headers |
map | {} |
Additional HTTP headers |
authToken |
String |
null |
Bearer token added to the Authorization header |
contentType |
String |
application/json |
Content-Type of the POSTed body |
reporters.email
| Option | Type | Default | Description |
|---|---|---|---|
host |
String |
required | SMTP server hostname |
port |
Int |
587 |
SMTP server port |
username |
String |
null |
SMTP authentication username |
password |
String |
null |
SMTP authentication password |
from |
String |
null |
Sender address (defaults to username) |
to |
String |
required | Recipient email address |
subject |
String |
"Karandash Validation Report" |
Email subject line |
starttls |
Boolean |
true |
Require STARTTLS. false sends plaintext and is accepted only for a loopback SMTP host (localhost, 127.0.0.1, ::1) |
reporters {
console = true
markdown = true
slack {
webhook = env.SLACK_WEBHOOK_URL
channel = "#code-review"
}
}
Plugins
| Option | Type | Default | Description |
|---|---|---|---|
install |
list | [] |
Declared plugins: an ID string, or an object with id (required), version and source (a URL to the plugin file) |
on-missing |
String |
warn |
warn, fail or ignore: what happens when a config entry names a module no loaded plugin provides |
When read from the config file, only install and on-missing take effect. Registry settings (registry-url,
token, auth-header) and directory are read by the karandash plugin commands from .karandash/manifest.yaml
only. Per-plugin config goes under the plugin's own section (for example rules: { custom-validator: { ... } }).
plugins:
on-missing: warn
install:
- com.example.jira-integration
- id: com.example.custom-validator
version: "1.0.0"
source: https://example.com/custom-validator.jar
Environment Variable References
The Kotlin DSL reads environment variables with env.VAR_NAME or env("VAR_NAME"); each becomes a ${VAR_NAME} placeholder, interpolated like YAML. Denylisted variables (secrets such as AWS_SECRET_ACCESS_KEY, and system variables such as PATH) read as unset; the top-level env: block supplies defaults for unset variables, also in a KTS if condition (see Environment Variables).
platforms {
gitlab {
url = env.CI_SERVER_URL
token = env.CI_JOB_TOKEN
}
}
AWS credentials
platforms.aws-codecommit and cache.remote (backend s3) take an optional profile key naming a shared-file
profile. Without access-key-id + secret-access-key both read credentials from the standard AWS chain - profile's
shared files, else AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ AWS_SESSION_TOKEN), else AWS_PROFILE/default
in ~/.aws/credentials / ~/.aws/config. The built-in chain reads the denylisted secret directly; ${AWS_SECRET_ACCESS_KEY}
interpolation stays blocked. The chain is only used for https AWS hosts (*.amazonaws.com, *.amazonaws.com.cn):
not for a custom CodeCommit endpoint/sts-endpoint or an S3-compatible cache.remote.url, whichever config layer (root or extends:
parent) sets cache.remote. See AWS CodeCommit.
Config File Discovery
Karandash searches for configuration files in this order:
.karandash/config.kts.karandash/config.yaml/.karandash/config.yml.karandash/config.json
If no file is found, zero-config mode activates with default rules.
See Also
- CLI Reference -- command-line flags that override config
- Environment Variables -- env vars for auth and overrides
- Error Codes -- exit codes for config errors