diff --git a/docs/src/layouts/Base.astro b/docs/src/layouts/Base.astro index c322cbc..553b29f 100644 --- a/docs/src/layouts/Base.astro +++ b/docs/src/layouts/Base.astro @@ -31,7 +31,7 @@ const pageTitle = title === 'Home' ? 'Warden' : `${title} | Warden`;
Setup - Skills + CLI diff --git a/docs/src/pages/cli.astro b/docs/src/pages/cli.astro new file mode 100644 index 0000000..8e152b1 --- /dev/null +++ b/docs/src/pages/cli.astro @@ -0,0 +1,323 @@ +--- +import Base from '../layouts/Base.astro'; +import Terminal from '../components/Terminal.astro'; +import { Code } from 'astro:components'; +--- + + +

CLI Reference

+ +

Warden provides a command-line interface for running code analysis locally and managing your configuration.

+ +

Quick Start

+ + + + + +

Commands

+ +
+

warden

+
warden [target] [options]
+

Run code analysis on the specified target. If no target is given, analyzes uncommitted changes.

+
    +
  • target — Files, directories, or git refs to analyze (optional)
    • +
+ + + +
+ +
+

warden init

+
warden init
+

Initialize Warden in your project. Creates a configuration file and GitHub workflow.

+ + 
$ warden init
+
+Created warden.toml
+Created .github/workflows/warden.yml
+
+Next steps:
+  1. Add a skill: warden add <skill-name>
+  2. Set WARDEN_ANTHROPIC_API_KEY in .env.local
+  3. Add WARDEN_ANTHROPIC_API_KEY to repository secrets
+  4. Commit and open a PR to test
+ +
+ +
+

warden add

+
warden add <skill-name>
+

Add a skill trigger to your configuration. The skill must already be installed.

+
    +
  • skill-name — Name of the skill to add (required)
    • +
+ + 
$ warden add security-review
+
+Added trigger for security-review to warden.toml
+ +
+ +
+

warden setup-app

+
warden setup-app [--org <name>]
+

Create a GitHub App for Warden. This gives you a custom bot identity instead of the generic "github-actions" user.

+
    +
  • --org <name> — Create the app for an organization instead of your personal account
    • +
+ + + +
+ +

Global Options

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescription
--skill <name>Run a specific skill instead of using triggers from config
--fixAutomatically apply suggested fixes
--jsonOutput results as JSON
--fail-on <level>Exit with error code if findings meet severity: critical, high, medium, low
--config <path>Path to config file (default: warden.toml)
--verboseShow detailed output
--helpShow help message
--versionShow version number
+ +

Target Types

+ +

Warden accepts different types of targets for analysis:

+ +

Files and Directories

+ +

Specify paths directly to analyze specific files or directories.

+ + + + + +

Git References

+ +

Use git refs to analyze changes between commits.

+ + + + + +

Environment Variables

+ + + + + + + + + + + + + + +
VariableDescription
WARDEN_ANTHROPIC_API_KEYYour Anthropic API key (required)
+ +

You can set this in a .env.local file in your project root for local development.

+ +

Examples

+ +

Pre-commit Check

+ +

Run before committing to catch issues early.

+ + + + + +

CI Integration

+ +

Use in CI scripts with JSON output and exit codes.

+ + + results.json + +# Review the output +cat results.json | jq '.findings[] | select(.severity == "high")'`} + lang="bash" + theme="vitesse-black" + /> + + +

Review PR Changes

+ +

Analyze all changes in a feature branch.

+ + + + + + + diff --git a/docs/src/pages/index.astro b/docs/src/pages/index.astro index f968eb6..1a6e84b 100644 --- a/docs/src/pages/index.astro +++ b/docs/src/pages/index.astro @@ -161,9 +161,9 @@ Analysis completed in 8.2s

Next Steps

- - Add your own skills -

Create custom reviewers in .warden/skills/

+ + CLI Reference +

Commands, options, and usage examples

 Configure triggers diff --git a/docs/src/pages/setup.astro b/docs/src/pages/setup.astro index 64a1c44..9e5cbc0 100644 --- a/docs/src/pages/setup.astro +++ b/docs/src/pages/setup.astro @@ -306,7 +306,7 @@ paths = ["src/api/**/*.ts"]`}

Custom Skills

-

Define custom skills in .warden/skills/. See the skills documentation for details.

+

Define custom skills in .warden/skills/.

Verify Setup

diff --git a/docs/src/pages/skills.astro b/docs/src/pages/skills.astro deleted file mode 100644 index b443e48..0000000 --- a/docs/src/pages/skills.astro +++ /dev/null @@ -1,352 +0,0 @@ ---- -import Base from '../layouts/Base.astro'; -import Terminal from '../components/Terminal.astro'; -import { Code } from 'astro:components'; - -const base = import.meta.env.BASE_URL.replace(/\/$/, ''); ---- - - -

Skills

- -

Skills are agents that analyze your pull requests. Each skill has a specific purpose, a prompt that guides the analysis, and restrictions on what tools it can use.

- -

Built-in Skills

- -

security-review

- -

Scans code changes for security vulnerabilities. This skill analyzes diffs for common security issues and reports findings with severity levels.

- -

What It Checks

- -
    -
  • Injection Vulnerabilities — SQL injection, command injection, XSS, template injection, path traversal
    • -
  • Authentication & Authorization — Missing auth checks, improper session handling, authorization bypass, hardcoded credentials
    • -
  • Data Security — Sensitive data exposure (PII, API keys), insecure storage, missing encryption, logging secrets
    • -
  • Dependencies — Known vulnerable packages, insecure configurations
    • -
  • General Security — Insecure crypto, race conditions, information disclosure, missing input validation
    • -
- -

Severity Levels

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
LevelDescription
criticalActively exploitable, high impact vulnerability
highExploitable with moderate effort
mediumPotential vulnerability, needs review
lowMinor security concern
infoSecurity-related observation
- -

Usage

- - - - - - - - - -

code-simplifier

- -

Identifies opportunities to reduce code complexity. This skill analyzes diffs for patterns that could be simplified, refactored, or made more readable.

- -

What It Checks

- -
    -
  • Nested Logic — Deeply nested conditionals, complex ternaries, callback pyramids
    • -
  • Redundant Code — Duplicate logic, unnecessary null checks, dead code
    • -
  • Long Functions — Functions that do too much, hard to test or maintain
    • -
  • Complex Expressions — Hard-to-read boolean logic, magic numbers, unclear naming
    • -
  • Modern Patterns — Opportunities to use optional chaining, nullish coalescing, destructuring
    • -
- -

Severity Levels

- - - - - - - - - - - - - - - - - - - - - - - - - - -
LevelDescription
highSignificant complexity that hurts maintainability
mediumModerate complexity worth addressing
lowMinor improvements for readability
infoStyle suggestions
- -

Usage

- - - - - - - - - -

Custom Skills

- -

Define your own skills in .warden/skills/ as TOML files.

- -

Skill Definition

- - - - - -

Skill Fields

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldRequiredDescription
nameYesUnique identifier (kebab-case)
descriptionYesHuman-readable purpose
promptYesSystem instructions for the agent
tools.allowedNoTools the skill can use
tools.deniedNoTools the skill cannot use
- -

Available Tools

- -

Skills can use Claude Code's built-in tools:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ToolDescription
ReadRead file contents
GrepSearch file contents with regex
GlobFind files by pattern
WebFetchFetch content from URLs (e.g., CVE databases)
WriteWrite files (usually denied for review skills)
EditEdit files (usually denied for review skills)
BashRun shell commands (usually denied for security)
- -

Using Custom Skills

- -

Reference your custom skill by name in triggers:

- - - - - -

Output Format

- -

Skills return findings in a structured format. Each finding includes:

- -
    -
  • Severity — How serious the issue is
    • -
  • Title — Brief description of the issue
    • -
  • Description — Detailed explanation
    • -
  • Location — File path and line numbers
    • -
  • Suggested Fix — Optional code suggestion
    • -
- -

Warden translates these findings into GitHub PR reviews with inline comments on the relevant lines.

- - -