CLI Reference
Complete reference for all Karandash CLI commands and flags.
Synopsis
karandash <command> [options]
Global description: MR validation tool with configurable rules.
Global options
-v/--debug and -q are read anywhere on the command line before -- (karandash -v validate and
karandash validate -v are the same); without them KARANDASH_LOG_LEVEL sets the level.
| Flag |
Short |
Description |
--version |
-V |
Print the version and exit |
--verbose, --debug |
-v |
Debug logging for every command, including plugin loading |
--quiet |
-q |
Suppress all output except errors |
Commands
Core Validation
| Command |
Description |
validate |
Validate a merge request against configured rules |
validate-local |
Validate local commits and diff against a target branch (no platform API) |
simulate |
Simulate approval policy evaluation against MR state |
test-rule |
Re-run a configured rule on real MRs (or summarize its recorded history) |
Configuration
| Command |
Description |
init |
Initialize a new Karandash configuration file |
wizard |
Interactive setup wizard for Karandash configuration |
config |
Validate config files and describe config keys |
explain |
Explain the effective config: what each rule and key does |
verify-policy |
Check the policies: block for contradictions |
profile |
List and apply named configuration profiles |
Analysis
| Command |
Description |
doctor |
Check configuration, authentication, and plugin health |
deps |
Analyze file conflicts and ordering dependencies between an MR and its siblings |
stats |
Show validation run statistics and rule violation trends |
calibrate |
Analyze rule thresholds and recommend calibration adjustments |
ai |
AI helpers: explain a rule, suggest a fix, draft a review reply or MR description (registered only when an AI provider env var is set) |
Reporting
| Command |
Description |
report |
Summarize a saved validation result JSON file |
format |
Print the data a report template sees and render a template against an example report |
mutate |
Run mutation tests against rule configuration |
Merge requests
| Command |
Description |
mr |
Merge, close or reopen a merge/pull request by URL |
Cache
| Command |
Description |
cache |
Manage the local and remote CAS cache |
Plugins
| Command |
Description |
plugin |
Manage karandash plugins |
Scaffolding
| Command |
Description |
generate |
Generate plugin scaffolding or JSON Schema |
validate-extends |
Validate a config inheritance chain |
Editor Support
| Command |
Description |
lsp |
Run the config language server over stdio for IDE extensions. The server answers textDocument/completion (rule ids inside rules {}, a rule's properties inside its block), textDocument/hover (a rule's description and properties) and publishes diagnostics from config validate on a .karandash/config.kts. JVM distribution (karandash.jar) only; native binaries exit 6 (EXECUTION_ERROR). Standalone server: ./gradlew :dsl:lsp-server:shadowJar builds dsl/lsp-server/build/libs/karandash-lsp.jar. |
karandash validate
Validate a merge request against configured rules.
Mode Selection
Karandash supports four modes of operation. Only one can be active at a time.
| Mode |
Flags |
Description |
| File mode |
--mr <path> |
Read MR data from a local JSON file |
| Live mode |
--mr-id, --platform, --project |
Fetch MR data from a platform API |
| PR URL mode |
--pr <url> |
Parse platform and IDs from a PR/MR URL |
| Auto-detect |
(none) |
Detect platform from CI environment or git remote |
Options
| Flag |
Short |
Type |
Default |
Description |
--config |
-c |
String |
auto-discovered |
Path to configuration file |
--mr |
-m |
String |
-- |
Path to MR data file (JSON) for file mode |
--mr-id |
-- |
String |
-- |
MR/PR identifier for live mode |
--platform |
-- |
String |
-- |
Platform name: gitlab, github, bitbucket, etc. |
--project |
-- |
String |
-- |
Project identifier (e.g., owner/repo) |
--pr |
-- |
String |
-- |
Full PR/MR URL for URL-based validation |
--format |
-f |
String |
console |
Output format: console, json, sarif, rdjsonl, rdjson. When set explicitly, only this reporter runs. |
--output |
-o |
String |
-- |
Write output to file |
--quiet |
-q |
flag |
false |
Suppress all output except errors |
--verbose |
-v |
flag |
false |
Show detailed validation output |
--trace |
-- |
flag |
false |
Verbose output plus full AI responses and per-rule AI diff file lists (same as KARANDASH_AI_TRACE=1) |
--strict |
-- |
flag |
false |
Treat warnings as failures (exit code 5) |
--baseline |
-- |
String |
-- |
JSON file of finding fingerprints to ignore; findings already in it are not reported |
--update-baseline |
-- |
flag |
false |
Rewrite the --baseline file from the current findings instead of applying it |
--dry-run |
-- |
flag |
false |
Validate config without running validation |
--explain |
-- |
flag |
false |
Show detailed explanations for each finding |
--fix |
-- |
flag |
false |
Automatically fix safe validation issues (labels, draft status) |
--yes |
-y |
flag |
false |
Skip confirmation prompts when using --fix |
--enrich |
-- |
flag |
false |
Run AI enrichment before validation (generate title/description) |
--dry-run-enrich |
-- |
flag |
false |
Preview AI enrichment without applying changes |
--dry-run-comment |
-- |
flag |
false |
Print comment body to console instead of posting to MR |
--show-prompt |
-- |
flag |
false |
With --dry-run: build every AI prompt without sending anything and write each to ai.debug.prompt-dir (the files hold MR source code; a directory the dump creates gets a .gitignore of *) |
--auto-approve |
-- |
flag |
false |
Automatically approve MR when all findings are below severity threshold |
--watch |
-w |
flag |
false |
Watch config file and re-run validation on changes |
--no-auto-detect |
-- |
flag |
false |
Disable platform auto-detection |
--on-missing-plugin |
-- |
String |
warn |
How to handle uninstalled modules: fail, warn, ignore |
--profile |
-- |
String |
-- |
Apply a named profile. Overrides profile in config file. |
--show-execution-plan |
-- |
flag |
false |
Print validation rules grouped by execution priority and exit |
--allow-localhost |
-- |
flag |
false |
Allow localhost and private IPs (disables SSRF protection) |
--dangerfile |
-- |
String |
auto-detected |
Path to Dangerfile.js or Dangerfile.df.kts |
--no-cache |
-- |
flag |
false |
Disable staleness gate cache - force full re-run of all rules and AI calls; nothing is read from the cache dir (state and cache entries are still saved for the next run) |
--invalidate-rules |
-- |
String |
-- |
Comma-separated rule IDs to invalidate from the cache |
--gate-on-cached |
-- |
Boolean |
false |
Cached findings merged into the report on a partial cache hit also gate the exit code and auto-approve |
--global-timeout |
-- |
String |
-- |
Global watchdog timeout (e.g. 600s, 10m). Overrides config. 0 = no timeout. |
--diagnostic |
-- |
String |
-- |
Write JSON runtime diagnostics to the given file path |
--dump-dir |
-- |
String |
-- |
Save every layer input/output of the run (config, MR, findings per stage, AI plans and calls) as numbered files; local debugging only, secrets redacted best-effort |
Usage Examples
# Auto-detect in CI (no flags needed)
karandash validate
# Live mode with explicit platform
karandash validate --mr-id 123 --platform github --project owner/repo
# File mode
karandash validate --mr test-data.json
# PR URL mode
karandash validate --pr https://github.com/owner/repo/pull/42
# JSON output to file
karandash validate --format json --output results.json
# SARIF output for code scanning
karandash validate --format sarif --output results.sarif
# Strict mode (warnings become failures)
karandash validate --strict
# Dry-run to verify config
karandash validate --dry-run
# Auto-fix with confirmation prompt
karandash validate --fix --mr-id 123 --platform github --project owner/repo
# Auto-fix in CI (no prompt)
karandash validate --fix --yes
# Watch mode (re-validate on config changes)
karandash validate --watch --mr test-data.json
# Custom config file
karandash validate -c custom-config.yaml --mr test-data.json
# Force cache bypass
karandash validate --no-cache
# Invalidate specific cached rules
karandash validate --invalidate-rules title-format,size-limits
Mutual Exclusions
--watch and --fix cannot be combined.
--mr (file mode) cannot be combined with --mr-id, --platform, or --project.
karandash init
Initialize a new Karandash configuration file.
Options
| Flag |
Short |
Type |
Default |
Description |
--output |
-o |
String |
.karandash/config.yaml |
Output path for configuration file |
--format |
-f |
String |
yaml |
Config format: yaml, json, kts |
--profile |
-- |
String |
-- |
Initialize config with a named profile (e.g. conventional-commits) |
Usage Examples
# Create default YAML config
karandash init
# Create Kotlin DSL config
karandash init --format kts
# Create config at custom path
karandash init --output .karandash/config.yaml
# Create JSON config
karandash init --format json --output .karandash/config.json
# Initialize from a named profile
karandash init --profile conventional-commits
If the configuration file already exists, init prints a message and exits without overwriting.
karandash doctor
Check configuration health, authentication, and plugin status.
Options
| Flag |
Description |
--plugins |
Show detailed plugin status table (built-in and community modules) |
--offline |
Skip the credential check against each platform API |
Exit Codes
| Code |
Meaning |
0 |
All checks passed |
1 |
Some checks failed (non-fatal) |
2 |
Config parse error (fatal) |
Usage
karandash doctor
karandash doctor --plugins
karandash wizard
Interactive setup wizard for Karandash configuration. Guides through platform selection, profile choice, and config format.
Options
| Flag |
Short |
Type |
Default |
Description |
--output |
-o |
String |
.karandash/config.yaml |
Output path for generated configuration |
--format |
-f |
String |
(wizard will ask) |
Output format: yaml, json, or kts |
--skip-detection |
-- |
flag |
false |
Skip automatic platform detection |
Usage
karandash wizard
karandash wizard --format kts
karandash wizard --skip-detection
karandash generate
Generate plugin scaffolding or a JSON Schema for IDE autocompletion.
Options
| Flag |
Short |
Type |
Required |
Description |
--schema |
-- |
flag |
No |
Generate JSON Schema and write to .karandash.schema.json |
--type |
-t |
String |
Yes (without --schema) |
Plugin type: rule, reporter, platform-service, provider, mutator, comment-poster (the last three scaffold the platform-service template) |
--name |
-n |
String |
Yes (without --schema) |
Plugin name (lowercase with hyphens) |
--package |
-p |
String |
No |
Base package name (default: io.karandash.plugin.<name>) |
--output |
-o |
String |
No |
Output directory (default: .) |
--init-git |
-- |
flag |
No |
Initialize a git repository in the generated project |
Usage Examples
# Generate a rule plugin scaffold
karandash generate --type rule --name my-rules
# Generate a reporter plugin scaffold
karandash generate --type reporter --name slack-reporter
# Generate JSON Schema for IDE autocompletion
karandash generate --schema
# Generate with custom package and output directory
karandash generate --type rule --name my-rule --package com.example.myrule --output plugins/
The plugin name must be lowercase with hyphens only (e.g., my-plugin).
karandash plugin
Manage karandash plugins. This is a group command with subcommands.
Subcommands
| Subcommand |
Description |
list |
List installed plugins |
install |
Install a plugin from a file or registry |
remove |
Remove an installed plugin by ID |
update |
Update installed plugins to latest versions |
create |
Create a new plugin project scaffold |
search |
Search the karandash plugin registry |
sign |
Sign a plugin JAR with a private key |
cache |
Manage the plugin download cache |
karandash plugin list
List installed plugins.
| Flag |
Type |
Default |
Description |
--plugin-dir |
String |
~/.karandash/plugins/ |
Plugin directory |
karandash plugin list
karandash plugin list --plugin-dir /opt/plugins
karandash plugin install
Install a plugin from a local file or the plugin registry.
| Argument |
Type |
Required |
Description |
path |
String |
No* |
Path to plugin file |
| Flag |
Type |
Default |
Description |
--plugin-dir |
String |
~/.karandash/plugins/ |
Plugin directory |
--registry |
String |
-- |
Plugin ID to install from the registry |
--pin |
flag |
false |
With --registry, upsert {id, version} into plugins.install of .karandash/manifest.yaml |
*Specify exactly one of path or --registry.
karandash plugin install build/libs/my-plugin-1.0.0.jar
karandash plugin install --registry io.karandash.plugins.jira-validator
karandash plugin remove
Remove an installed plugin by its module ID.
| Argument |
Type |
Required |
Description |
id |
String |
Yes |
Plugin module ID to remove |
| Flag |
Type |
Default |
Description |
--plugin-dir |
String |
~/.karandash/plugins/ |
Plugin directory |
karandash plugin remove my-custom-rules
karandash plugin update
Update installed plugins to their latest versions.
| Argument |
Type |
Required |
Description |
plugin-id |
String |
No |
Plugin ID to update (omit to update all) |
| Flag |
Short |
Type |
Default |
Description |
--check-only |
-c |
flag |
false |
Only check for updates, don't install |
--yes |
-y |
flag |
false |
Skip confirmation prompts |
--plugin-dir |
-- |
String |
~/.karandash/plugins/ |
Plugin directory |
karandash plugin update
karandash plugin update --check-only
karandash plugin update io.karandash.rules --yes
karandash plugin create
Create a new plugin project from a template.
| Argument |
Type |
Required |
Description |
name |
String |
Yes |
Plugin name (lowercase, alphanumeric with hyphens) |
| Flag |
Type |
Default |
Description |
--type |
String |
rule |
Plugin type: rule, reporter, platform-service, provider, mutator, comment-poster (the last three scaffold the platform-service template) |
--package |
String |
io.example.<name> |
Base package name |
--no-git |
flag |
false |
Skip git repository initialization |
# Create a rule plugin
karandash plugin create my-rules
# Create a reporter plugin
karandash plugin create slack-reporter --type reporter
# Create with custom package, no git init
karandash plugin create my-rule --package com.example.myrule --no-git
karandash plugin search
Search the karandash plugin registry.
| Argument |
Type |
Required |
Description |
query |
String |
No |
Search query (matches name, description, tags) |
| Flag |
Type |
Default |
Description |
--tag |
String |
-- |
Filter by tag |
--type |
String |
-- |
Filter by plugin type |
--refresh |
flag |
false |
Force refresh the registry cache |
# Search by keyword
karandash plugin search jira
# Filter by tag
karandash plugin search --tag integration
# Filter by type
karandash plugin search --type reporter
# Refresh cache and list all
karandash plugin search --refresh
karandash plugin sign
Sign a plugin JAR with a private key for integrity verification.
| Argument |
Type |
Required |
Description |
jar-file |
String |
Yes |
Path to the plugin JAR file |
| Flag |
Short |
Required |
Description |
--key |
-- |
Yes |
Path to private key file (RSA, PKCS#8 or PKCS#1 DER) |
--output |
-o |
No |
Output path for signature file (default: <jar-file>.sig) |
karandash plugin sign my-plugin-1.0.0.jar --key private.der
karandash plugin sign my-plugin.jar --key private.der -o custom.sig
karandash plugin cache
Manage the plugin download cache.
karandash plugin cache clear
Clear all cached remote plugin downloads.
karandash plugin cache clear
| Format |
Flag |
Description |
console |
--format console |
Human-readable terminal output (default) |
json |
--format json |
Machine-readable JSON output |
sarif |
--format sarif |
SARIF format for code scanning integrations |
rdjson |
--format rdjson |
Reviewdog JSON format |
rdjsonl |
--format rdjsonl |
Reviewdog JSON Lines format (no envelope) |
See Also