npm package: @qraft-cli/cli
Description: Qraft CLI — Spec, test, and domain knowledge management for AI-driven development
Latest version: 0.1.0

# 💻 Qraft CLI

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

## Installation

```bash
# 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:

```bash
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.

```bash
qraft init
```

### `qraft specs [search]`

List and search specifications.

```bash
# 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`.

```bash
# 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:**

```json
[
  {
    "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.

```bash
# 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.

```bash
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](../../LICENSE)