💻 Qraft CLI

Manage specifications, report test results, and explore domain knowledge from your terminal.

Installation

# From the monorepo
pnpm install
pnpm --filter @qraft/cli build

# Run directly
npx @qraft/cli <command>

# Or link globally
pnpm --filter @qraft/cli link --global
qraft <command>

Setup

Initialize your CLI configuration:

qraft init

You'll be prompted for:

| Setting | Description | |---------|-------------| | API URL | Qraft server URL (e.g., https://your-qraft.vercel.app) | | API Key | Your API key (starts with dlk_) | | Project ID | Target project UUID |

Configuration is saved locally for subsequent commands.

Commands

qraft init

Interactive setup wizard. Validates connection and saves configuration.

qraft init

qraft specs [search]

List and search specifications.

# List all specs
qraft specs

# Search by keyword
qraft specs "authentication"

# Filter by type and status
qraft specs --type functional --status approved

# Limit results
qraft specs --limit 5

Options:

| Flag | Description | |------|-------------| | --type <type> | Filter by spec type (e.g., functional, technical) | | --status <status> | Filter by status (draft, review, approved, deprecated) | | --limit <n> | Maximum number of results |

qraft test report

Register test results from a file or stdin. Supports popular test framework formats via --format.

# Qraft native JSON format (default)
qraft test report --suite-id <uuid> --file results.json

# Jest (--json flag)
npx jest --json --outputFile=jest-results.json
qraft test report --suite-id <uuid> --format jest --file jest-results.json

# Vitest (--reporter=json)
npx vitest run --reporter=json --outputFile=vitest-results.json
qraft test report --suite-id <uuid> --format vitest --file vitest-results.json

# JUnit XML (Maven Surefire / pytest --junit-xml)
qraft test report --suite-id <uuid> --format junit --file junit-combined.xml

# Go test -json (NDJSON streaming output)
go test -json ./... > go-results.json
qraft test report --suite-id <uuid> --format go --file go-results.json

# From stdin
cat jest-results.json | qraft test report --suite-id <uuid> --format jest

# With CI metadata
qraft test report \
  --suite-id <uuid> \
  --format jest \
  --file jest-results.json \
  --triggered-by ci \
  --github-run-id "$GITHUB_RUN_ID"

Options:

| Flag | Description | |------|-------------| | --suite-id <id> | (Required) Test suite UUID | | --file <path> | Path to results file | | --format <fmt> | Input format: json (default), jest, vitest, junit, go | | --triggered-by <trigger> | Trigger source (e.g., ci, manual) | | --github-run-id <id> | GitHub Actions run ID |

Supported formats:

| Format | Framework | How to generate | |--------|-----------|----------------| | json | Qraft native | Manual / API | | jest | Jest | jest --json --outputFile=results.json | | vitest | Vitest | vitest run --reporter=json --outputFile=results.json | | junit | Maven, pytest, JUnit | mvn test (Surefire XML) / pytest --junit-xml=results.xml | | go | Go test | go test -json ./... > results.json |

Qraft native JSON format:

[
  {
    "testCaseId": "uuid",
    "status": "passed",
    "durationMs": 120,
    "errorMessage": null
  }
]

GitHub Actions Integration

Pre-built workflow templates are available in .github/workflows/:

| File | Framework | |------|-----------| | qraft-jest.yml | Jest | | qraft-vitest.yml | Vitest | | qraft-junit.yml | Maven (Java) + pytest (Python) | | qraft-go.yml | Go |

Required repository secrets/variables:

| Key | Type | Description | |-----|------|-------------| | QRAFT_API_URL | Secret | Qraft server URL | | QRAFT_API_KEY | Secret | API key (dlk_...) | | QRAFT_SUITE_ID | Variable | Test suite UUID |

qraft glossary [search]

Browse and search the domain glossary.

# List all terms
qraft glossary

# Search by keyword
qraft glossary "payment"

# Filter by category
qraft glossary --category billing

Options:

| Flag | Description | |------|-------------| | --category <cat> | Filter by glossary category |

qraft domain context <name>

Get full domain context for an entity or term — related entities, glossary terms, rules, specs, and tests.

qraft domain context User
qraft domain context "Payment Method" --depth 2

Options:

| Flag | Description | |------|-------------| | --depth <n> | Relationship traversal depth |

Configuration

The CLI stores configuration in your home directory. Run qraft init to set up or update.

License

MIT