# query

The `query` command lets you search xtarterize tasks using natural language - no need to remember exact task IDs. It uses a pure algorithmic scoring engine (no AI) to rank tasks by relevance to your query.

## Usage

```bash frame="none"
xtarterize query "<query>" [options]
```

A query is any natural language description of the tooling setup you're looking for.

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--json` | Output machine-readable JSON | `false` |
| `--limit <n>` | Maximum number of results to show | `20` |
| `--threshold <n>` | Minimum relevance score (0-1) | `0.1` |
| `--timing` | Show detailed per-task timing breakdown | `false` |
| `--cwd <path>` | Target directory | current directory |

### Global options

This command does not support global formatting or output flags (`--quiet`, `--format`). Use `--json` for machine-readable output.

## Examples

### Find tasks by description

```bash
xtarterize query "strict typescript"
```

Outputs tasks grouped by domain bundle with per-group actionable add commands:

```
✻ xtarterize query "strict typescript" - 2 groups · 4 tasks

  TypeScript
  ts/strict                80%  tsconfig - strict: true             tsconfig.json
  ts/paths                 52%  tsconfig - path aliases             tsconfig.json
  ts/incremental           24%  tsconfig - incremental: true        tsconfig.json
  gitignore/tsbuildinfo    14%  .gitignore - tsbuildinfo             .gitignore

  xtarterize add ts/strict ts/paths ts/incremental gitignore/tsbuildinfo
  xtarterize add scripts/package-scripts
```

### Search for linting and formatting

```bash
xtarterize query "linting and formatting tool" --limit 5
```

### Machine-readable output

```bash
xtarterize query "ci pipeline" --json
```

```json
{
  "type": "query",
  "query": "ci pipeline",
  "count": 3,
  "results": [
    {
      "taskId": "ci/ci",
      "label": "GitHub CI workflow",
      "group": "CI/CD",
      "relevance": 0.85,
      "signals": [
        { "name": "label", "score": 1.0 },
        { "name": "id", "score": 0.85 },
        { "name": "keywords", "score": 0.9 },
        { "name": "config", "score": 1.0 },
        { "name": "group", "score": 1.0 }
      ]
    }
  ]
}
```

### Compose an init plan

Combine query with the init workflow to get a ranked task plan:

```bash
xtarterize init --compose "react project with ci and linting"
```

This reorders tasks so the most relevant ones appear first in the interactive plan, without excluding any applicable tasks.

## How It Works

The scoring engine operates in five steps:

1. **Tokenize** - The query is split into words; stopwords (a, the, want, need, project, etc.) and short words are filtered out
2. **Expand** - Content words are expanded through a domain-specific synonym map with bidirectional transitive reverse-lookup (e.g. "lint" → "linter", "static-analysis", "check"; "typescript" → "ts", "type-safe", "strict")
3. **Score** - For each original token, find the best match across all 5 signals (label, id, group, keywords, config targets) using the highest signal score among all terms (original + expanded synonyms). Uses tiered match levels: exact (1.0), stem-match (0.95), fuzzy (0.85), prefix (0.75), substring (0.55)
4. **Aggregate** - Signal scores are weighted and averaged; multi-token queries receive a coverage bonus that increases with the proportion of tokens matched
5. **Group** - Results are organized by task group/domain bundle, with per-group actionable `xtarterize add` commands

**Note:** The scoring engine is entirely algorithmic - zero AI model calls, zero API dependencies.
  It runs offline and completes in milliseconds.

## See Also

- [CLI Overview](/xtarterize/guide/cli/overview/) - full command reference
- [Tasks Overview](/xtarterize/guide/tasks/overview/) - understanding tasks and their metadata