warden init

Initialize Warden in your repository with configuration and workflows

Overview

The warden init command sets up Warden in your repository by creating:

• warden.toml - Configuration file with example skills
• .github/workflows/warden.yml - GitHub Actions workflow
• .agents/skills/ - Directory for custom skills (optional)

Usage

npx warden init

Interactive Setup

The init command runs interactively by default:

$ npx warden init

🔧 Initializing Warden in your repository...

✓ Created warden.toml
✓ Created .github/workflows/warden.yml
✓ Created .agents/skills/ directory

Next steps:
  1. Add your ANTHROPIC_API_KEY to GitHub Secrets
  2. Customize warden.toml for your project
  3. Run 'npx warden' to analyze your code

Generated Files

warden.toml

A basic configuration file is created:

warden.toml

version = 1

[defaults]
# Fail CI on high+ severity findings
failOn = "high"
# Show annotations for medium+ severity
reportOn = "medium"

[[skills]]
name = "code-quality"
paths = ["src/**"]

[[skills.triggers]]
type = "local"

[[skills.triggers]]
type = "pull_request"
actions = ["opened", "synchronize", "reopened"]

You can customize this file after creation. See Configuration Guide.

.github/workflows/warden.yml

A GitHub Actions workflow is created:

.github/workflows/warden.yml

name: Warden
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  warden:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: getsentry/warden@v1
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

This workflow:

• Runs on all PR events
• Requires ANTHROPIC_API_KEY secret
• Posts findings as PR comments

.agents/skills/

An empty directory for custom skills:

.agents/
└── skills/
    └── (your custom skills here)

Add your own skills here. See Creating Skills.

Options

—force

Overwrite existing files:

npx warden init --force

This overwrites warden.toml and .github/workflows/warden.yml without confirmation.

—skip-workflow

Skip creating the GitHub Actions workflow:

npx warden init --skip-workflow

Useful if you’re only using Warden locally or have a custom CI setup.

—skip-skills-dir

Skip creating the .agents/skills/ directory:

npx warden init --skip-skills-dir

Next Steps

1. Add API key to GitHub Secrets

   Go to your repository Settings → Secrets and variables → Actions and add ANTHROPIC_API_KEY.

2. Customize warden.toml

   Edit the generated config to match your project:

   warden.toml

   [[skills]]
   name = "security-audit"
   paths = ["src/**/*.ts"]
   ignorePaths = ["**/*.test.ts"]
   failOn = "medium"
   
3. Run your first analysis

   Test Warden locally:

   npx warden
   
4. Open a pull request

   Create a PR to see Warden in action on GitHub.

Examples

Initialize with custom config

Create a minimal config:

$ npx warden init
$ cat warden.toml

Then customize:

warden.toml

version = 1

[defaults]
failOn = "high"
reportOn = "low"
ignorePaths = ["dist/**", "node_modules/**"]

[[skills]]
name = "find-bugs"
paths = ["src/**/*.ts"]
model = "claude-sonnet-4-20250514"

[[skills.triggers]]
type = "local"

[[skills.triggers]]
type = "pull_request"
actions = ["opened", "synchronize"]
failOn = "medium"

Initialize in monorepo

For monorepos, initialize at the root:

cd packages/api
npx warden init

Customize paths:

warden.toml

[[skills]]
name = "code-quality"
paths = ["packages/api/src/**"]

Initialize without GitHub integration

Skip workflow creation:

npx warden init --skip-workflow

Use in other CI systems:

.gitlab-ci.yml

warden:
  script:
    - npx warden
  only:
    - merge_requests

Troubleshooting

init fails with 'warden.toml already exists'

Use --force to overwrite:

npx warden init --force

Or manually remove the file:

rm warden.toml
npx warden init

Workflow not running on PRs

Verify:

1. .github/workflows/warden.yml exists
2. Workflow is enabled in Actions tab
3. ANTHROPIC_API_KEY secret is set
4. Workflow has required permissions

Want to add more skills after init

Use warden add to add skills:

npx warden add

Or edit warden.toml manually.

Related

Configuration

Complete warden.toml reference

Add skills

Add more skills after init

GitHub Action setup

Advanced workflow configuration

Creating skills

Write custom skills