# CLI Reference
Complete command reference for Checkmate.
## Global Options
```
-h, --help Print help
-V, --version Print version
```
## Commands Overview
| `cm init` | Initialize Checkmate in current directory |
| `cm test` | Run API tests |
| `cm config` | Configuration management |
| `cm history` | Show test run history |
| `cm show` | Show details of a specific run |
| `cm docs` | Show documentation overview |
| `cm doc` | Show category-specific documentation |
| `cm onboard` | Quick-start guide for AI agents |
| `cm prime` | Output project context (for hooks) |
| `cm clove` | JSON query language operations |
| `cm spec` | Manage test specifications |
| `cm report` | Report generation |
---
## cm init
Initialize Checkmate in current directory.
```bash
cm init [OPTIONS]
```
### Options
| `-L, --url <URL>` | Base URL for API tests (required in non-interactive mode) |
| `--stealth` | Add .checkmate/ to .git/info/exclude |
### Examples
```bash
# Interactive mode (prompts for URL)
cm init
# Non-interactive mode
cm init --url http://localhost:8080
# Stealth mode (local only, not tracked in git)
cm init --url http://localhost:8080 --stealth
```
### Behavior
- **TTY mode**: Prompts for base URL interactively
- **Non-TTY mode**: Requires `--url` flag, shows error with instructions otherwise
### Created Structure
```
.checkmate/
├── config.toml # Project configuration
├── tests/ # Test specifications
├── runs/ # Test run history
└── hooks/ # Lifecycle hook scripts
```
---
## cm test
Run API tests.
### cm test run
Run test specifications.
```bash
cm test run [OPTIONS] [SPECS]...
```
#### Arguments
| `[SPECS]...` | Test spec files to run (optional) |
#### Options
| `-t, --test <TEST>` | Run specific test by name |
| `-v, --verbose` | Verbose output |
#### Examples
```bash
# Run all discovered specs
cm test run
# Run specific spec by name
cm test run users
# Run specific spec by path
cm test run ./custom/test.yaml
# Run multiple specs
cm test run users orders payments
# Run with verbose output
cm test run -v
# Run specific test within a spec
cm test run users --test user_creation
```
#### Auto-Discovery
When no specs provided:
1. Discovers `.checkmate/` by walking up directory tree
2. Finds all `.yaml`/`.yml` files in `.checkmate/tests/`
3. Runs them in alphabetical order
#### Name Resolution
Spec names are resolved in order:
1. If path exists, use as-is
2. Try `.checkmate/tests/{name}.yaml`
3. Try `.checkmate/tests/{name}.yml`
### cm test list
List available tests in spec files.
```bash
cm test list [SPECS]...
```
#### Examples
```bash
# List all tests
cm test list
# List tests in specific spec
cm test list users
```
### cm test validate
Validate test specs without running.
```bash
cm test validate [SPECS]...
```
Checks YAML syntax and schema without making HTTP requests.
---
## cm config
Configuration management.
### cm config show
Show current configuration.
```bash
cm config show [OPTIONS]
```
#### Options
| `--json` | Output as JSON instead of TOML |
#### Examples
```bash
# Show as TOML
cm config show
# Show as JSON
cm config show --json
```
### cm config sources
Show configuration sources and which are active.
```bash
cm config sources
```
Output:
```
Configuration sources (in priority order):
[ ] User: ~/.config/checkmate/config.toml (not found)
[✓] Project: /path/to/.checkmate/config.toml
Environment variables: CM_* (e.g., CM_ENV__BASE_URL)
```
---
## cm history
Show test run history.
```bash
cm history [OPTIONS]
```
### Options
| `--commit <COMMIT>` | Filter by git commit |
| `--spec <SPEC>` | Filter by spec file name |
| `-n, --limit <LIMIT>` | Maximum results [default: 10] |
### Examples
```bash
# Recent runs
cm history
# More results
cm history -n 20
# Filter by spec
cm history --spec users
# Filter by commit
cm history --commit abc123
```
### Output Format
```
✓ cm-run-a3f 2024-01-15 5/5 passed @ abc1234*
✗ cm-run-b7c 2024-01-14 3/5 passed @ def5678
```
- `✓` = all passed, `✗` = failures
- `*` after commit = dirty working directory
---
## cm show
Show details of a specific run.
```bash
cm show <RUN_ID>
```
### Example
```bash
cm show cm-run-a3f
```
Output:
```
Run: cm-run-a3f
Time: 2024-01-15T10:30:00Z
Spec: users.yaml
Results: 5/5 passed, 0 failed, 0 errors (1234ms)
Git Context:
Commit: abc1234
Branch: main
Dirty: no
Message: Add user validation
```
---
## cm docs
Show documentation overview.
```bash
cm docs
```
Lists all available documentation categories.
---
## cm doc
Show category-specific documentation.
```bash
cm doc <CATEGORY>
```
### Categories
| `assertions` | Assertion types and examples |
| `requests` | Request definition format |
| `env` | Environment and configuration |
| `scopes` | Clove query scopes |
| `examples` | Complete examples |
| `cli` | CLI reference |
### Example
```bash
cm doc assertions
```
---
## cm onboard
Quick-start guide for AI agents.
```bash
cm onboard
```
Outputs a condensed reference for AI agents covering test spec format, running tests, and common patterns.
---
## cm prime
Output project context for AI agents.
```bash
cm prime
```
Used by SessionStart hooks to inject context. Outputs:
- Project location and base URL
- Available test specs with test counts
- Recent run history
- Quick reference commands
Silently exits if no `.checkmate/` found.
---
## cm clove
JSON query language operations.
```bash
cm clove <COMMAND>
```
### cm clove eval
Evaluate a Clove expression against JSON.
```bash
cm clove eval '<expression>' '<json>'
```
### cm clove parse
Parse and display AST of a Clove expression.
```bash
cm clove parse '<expression>'
```
---
## Environment Variables
Override configuration with `CM_` prefix:
| `CM_ENV__BASE_URL` | Override base URL |
| `CM_ENV__TIMEOUT_MS` | Override timeout |
| `CM_DEFAULTS__FAIL_FAST` | Stop on first failure |
| `CM_DEFAULTS__EXPECT_STATUS` | Default expected status |
Note: Use double underscore (`__`) for nested keys.
---
## Exit Codes
| 0 | Success |
| 1 | Test failures or errors |
---
## See Also
- [Quick Start](QUICKSTART.md)
- [Test Specs](TEST_SPECS.md)
- [Configuration](CONFIG.md)