CLI Commands

verikt guide

Generate architecture context for AI coding agents. Reads your verikt.yaml and outputs rules, dependency constraints, and anti-patterns that AI agents consume before writing code.

verikt guide [flags]

Flags

Flag	Description	Default
--target	AI tool target (all, claude, cursor, copilot, windsurf)	all
--path	Path to project	.
--output	Output format (terminal, file)	terminal

Examples

# Generate context for any AI agent
verikt guide

# Target Claude Code specifically
verikt guide --target claude

# Target Cursor
verikt guide --target cursor

Tip

Prevention beats correction. Feed your AI agent the architecture rules before it writes code, and it produces correct code from the first line.

---

verikt new

Scaffold a new project.

verikt new [name] [flags]

Flags

Flag	Description	Default
--name	Project/service name	positional arg
--arch	Architecture pattern (hexagonal, flat)	hexagonal
--cap	Capabilities (comma-separated)	none
--module	Go module path	example.com/<name>
--output-dir	Output directory	.
--no-wizard	Disable interactive wizard	false
--set	Template variable (key=value), repeatable	none
--language	Project language	go

Version Detection and Features

By default, verikt runs go env GOVERSION to detect the installed Go version. The detected version is used to resolve feature flags from the provider’s feature matrix — enabling modern stdlib APIs and language features in the generated code.

You can override the detected version with --set GoVersion=X.XX. This is useful in CI environments or when targeting a specific Go version different from the one installed locally.

# Use detected Go version (default)
verikt new my-service --language go --no-wizard

# Target a specific Go version
verikt new my-service --language go --set GoVersion=1.24 --no-wizard

See the Feature Matrix for the full list of version-gated features.

Examples

# Interactive wizard — guides you through every choice
verikt new my-service --language go

# Non-interactive with all options
verikt new my-service \
  --language go \
  --arch hexagonal \
  --cap platform,bootstrap,http-api,mysql,docker \
  --module github.com/myorg/my-service \
  --no-wizard

# Target Go 1.24 features explicitly
verikt new my-service --language go --set GoVersion=1.24 --no-wizard

verikt check

Validate a project against its verikt.yaml rules.

verikt check [flags]

Flags

Flag	Description	Default
--path	Path to project	.
--output	Output format (terminal, json)	terminal

What It Does Not Analyse

Test files (_test.go) are excluded from every check, including dependency rules. A test reaches across layers to assemble a fixture, so counting its imports reports violations for code that is not part of the architecture. The consequence is worth knowing before you design around it: an import that only exists in a test will not be flagged.

Generated files are excluded. A file carrying Go’s // Code generated ... DO NOT EDIT. marker before its package clause is skipped — regenerating it would restore any finding, so the finding is not actionable.

Nested modules are excluded. A directory with its own go.mod is a different project; its packages belong to that module’s import path. Point --path at it to analyse it on its own.

What It Checks

verikt runs 14 AST-based detectors:

• Dependency violations — imports that cross component boundaries
• Required directories — components with missing directories
• Forbidden directories — directories that shouldn’t exist
• Function complexity — functions exceeding line/param/return limits
• Component coverage — percentage of components with source files
• Anti-patterns — common architectural violations

Exit Codes

Code	Meaning
0	No error-severity violations. Warnings may be present.
1	An error-severity violation was found, or a proxy rule could not run

Warnings never affect the exit code, so a finding you have chosen to live with cannot block a pipeline. The exit code is the same in every output format — --output json reports the same verdict it prints.

A proxy rule whose scope matches no files is reported as stale and fails the check: a rule that did not run has not passed. A rule that ran and found nothing is passing, not stale.

Waiving a Finding

Any finding can be waived with severity_overrides, anti-patterns included. A waiver requires a reason, so the justification lands in the diff where a reviewer sees it:

severity_overrides:
  god_package:
    - severity: ignore
      reason: "the shared domain vocabulary; 27 types + 15 constants, nothing to trim"
      paths: ["internal/core/**"]

Waived findings are still reported, in a WAIVED section and in the waived[] array of the JSON output, and they do not affect the exit code. A finding that disappeared entirely would be indistinguishable from one the detector never found.

JSON Output

--output json emits a schema_version field. Check it before parsing — key names are stable within a version, not across them.

violations[], anti_patterns[] and waived[] are always present and always arrays, so they are safe to iterate on a passing project.

{
  "schema_version": 2,
  "result": "fail",
  "violations": [
    { "severity": "error", "file": "domain/order.go", "rule": "dependency", "message": "..." }
  ],
  "anti_patterns": [
    { "severity": "error", "name": "sql_concatenation", "file": "repo/db.go", "message": "..." }
  ],
  "waived": [
    { "category": "anti_pattern", "rule": "god_package", "file": "internal/core", "reason": "..." }
  ]
}

To gate a pipeline, read result:

verikt check --output json > verikt.json
jq -e '.result == "pass"' verikt.json

result is the same verdict the exit code carries, so gating on either is equivalent — and it accounts for every category. Selecting on severity across violations[] and anti_patterns[] does not: those two arrays hold the built-in detector findings only. An error-severity proxy-rule violation lives in proxy_rules.violations[], a rule that could not run appears only in proxy_rules.statuses[], and decision-gate failures are in decision_violations[]. A gate built from the two top-level arrays passes on all three.

To count findings by severity — for a debt report rather than a gate — include every source:

jq '[(.violations // [])[], (.anti_patterns // [])[], (.proxy_rules.violations // [])[]]
    | group_by(.severity) | map({severity: .[0].severity, count: length})' verikt.json

Example Output

verikt check

Architecture: hexagonal
Components: 4 defined

Dependency Violations: 0
Structure Issues: 0
Function Issues: 0

Component Coverage: 100% (4/4)
Compliance: 100%

✓ All checks passed

verikt analyze

Analyze an existing project’s architecture.

verikt analyze [flags]

Flags

Flag	Description	Default
--path	Path to project	.
--output	Output format (terminal, json)	terminal

Tip

Use verikt analyze on existing projects to understand their structure before adding an verikt.yaml for enforcement.

verikt add

Add one or more capabilities to an existing project.

verikt add <capability> [capability...] [flags]

Capabilities are validated against the provider’s templates, conflicts are checked, and transitive dependencies are auto-resolved. Existing files are never overwritten — only new files are created.

Flags

Flag	Description	Default
--dry-run	Show what would be added without writing any files	false

--dry-run reports the files it would create and which capabilities it would resolve, and leaves verikt.yaml and the generated guides untouched.

What It Does

1. Finds verikt.yaml in the current directory
2. Validates that each capability exists and doesn’t conflict
3. Auto-resolves transitive dependencies (e.g., bff pulls in http-api)
4. Renders only new capability files, skipping any that already exist on disk
5. Updates verikt.yaml with the new capabilities
6. Regenerates verikt guide output

Examples

# Add a single capability
verikt add redis

# Add multiple capabilities at once
verikt add kafka-consumer observability

# Add a capability with transitive deps
verikt add bff  # auto-adds http-api if not present

Example Output

Adding capabilities:
  + http-api (auto-dependency)
  + bff
  Created: adapter/httphandler/handler.go
  Created: adapter/httphandler/router.go
  Skipped (exists): config/config.go

Done: 5 files created, 1 files skipped, 2 capabilities added
Auto-resolved dependencies: http-api

---

verikt diff

Show structural drift between verikt.yaml and files on disk. Like terraform plan for code architecture.

verikt diff [flags]

Flags

Flag	Description	Default
--path	Project path to diff	.
-o, --output	Output format (terminal, json, markdown)	terminal

What It Reports

For each capability declared in verikt.yaml, diff checks whether the expected files exist:

Status	Meaning
ok	All expected files are present
partial	Some files present, some missing
missing	All expected files are missing

The drift score (0.00 = perfect, 1.00 = completely drifted) tells you how far reality has diverged from the declared architecture.

Examples

# Check drift in current project
verikt diff

# Check a specific project
verikt diff --path ./my-service

# Get JSON output for CI
verikt diff -o json

Example Output

verikt Diff — hexagonal + 4 capabilities
═══════════════════════════════════════════════════════
  ✓ architecture       all files present
  ✓ http-api           all files present
  ✗ redis              2 missing files
    - adapter/redisrepo/connection.go
    - adapter/redisrepo/repository.go
  ✓ docker             all files present

═══════════════════════════════════════════════════════

Summary: 3/4 capabilities fully present | drift score: 0.12

Tip

Use verikt diff -o json in CI pipelines to fail builds when drift exceeds a threshold.

---

verikt init

Initialize an verikt.yaml for an existing project.

verikt init [flags]

Flags

Flag	Description	Default
--path	Path to project	.
--no-wizard	Skip interactive wizard	false
--force	Overwrite existing verikt.yaml	false

Note

This is useful for adding architecture enforcement to projects that weren’t scaffolded with verikt. Use verikt analyze first to understand the existing structure.

---

verikt version

Print version, commit hash, and build date.

verikt version

Example Output

verikt version 1.0.0
commit: 6d22600
built: 2026-03-11T12:00:00Z

---

Global Flags

These flags are available on all commands:

Flag	Description	Default
--no-color	Disable colored output	false
-o, --output	Output format (terminal, json, markdown)	terminal