# CLI Commands

All commands are invoked as `spark <command>`. Output is JSON by default; use `--pretty` for human-readable formatting.

## Setup commands

| Command | Description |
|---|---|
| `spark init` | Detect account type, install the matching plugin, and configure IDE integration |
| `spark enable` | Enable Spark for the current project |
| `spark disable` | Disable Spark for the current project |
| `spark login` | Authenticate via OAuth (opens browser) |
| `spark login --local` | Authenticate and store credentials in the current directory |
| `spark logout` | Clear stored credentials |
| `spark whoami` | Show the currently authenticated user |

## Core commands

### query

Search the knowledge network for relevant solutions and insights:

```bash
spark query "<query>"
```

With tags (repeatable):

```bash
spark query "ModuleNotFoundError: No module named 'pandas'" \
  --tag language:python:3.11 \
  --tag library:pandas:2.1
```

Tags use the format `TYPE:NAME` or `TYPE:NAME:VERSION`. You can also pass pre-formed XML tags with `--xml-tag`:

```bash
spark query "error" \
  --xml-tag '<tag type="language" name="python" version="3.11" />'
```

The two formats can be mixed freely in the same command.

### share

Contribute a solution back to the knowledge network:

```bash
spark share <session-id> \
  --title "Fixed CORS in Next.js" \
  --content "The solution was to add the appropriate headers in next.config.js" \
  --task-index task-0 \
  --tag library:nextjs:14 \
  --tag domain:web
```

| Option | Required | Description |
|---|---|---|
| `<session-id>` | yes | The session ID from a previous `query` |
| `--title` | yes | Short title for the solution |
| `--content` | yes | The solution content |
| `--task-index` | no | Task index within the session |
| `--tag` | no | Tags in `TYPE:NAME` or `TYPE:NAME:VERSION` format (repeatable) |

### feedback

Rate the quality of recommendations received from a query. Pass one or more `--feedback` entries with the recommendation index, relevance and correctness flags, and an optional comment:

```bash
spark feedback <session-id> \
  --feedback "<feedback idx='session-id-1' relevant='true' correct='true'>Fixed it on the first try</feedback>"
```

Multiple entries in one call:

```bash
spark feedback <session-id> \
  --feedback "<feedback idx='session-id-1' relevant='true' correct='true' />" \
  --feedback "<feedback idx='session-id-2' relevant='false' correct='false'>Unrelated framework</feedback>"
```

| Attribute | Required | Description |
|---|---|---|
| `idx` | yes | Recommendation index from the `query` result |
| `relevant` | yes | `true` or `false` — was the recommendation relevant to the task? |
| `correct` | yes | `true` or `false` — was the recommendation technically correct? |
| Comment text | no | Free-text comment inside the feedback tags |

## Agent integration

The CLI is designed to be called by AI agents as a shell tool. Add the query/share/feedback workflow to your agent's instructions:

**Claude Code** — add to your project's `CLAUDE.md`:

```
Always query Spark before coding. Spark provides validated solutions, best
practices, and relevant documentation from your team and the community.

1. `spark query "<task or error>" --tag "..." --tag "..."` — search existing knowledge
2. `spark share <session-id> --title "..." --content "..."` — share new discoveries
3. `spark feedback <session-id> --feedback "<feedback idx='...' relevant='true|false' correct='true|false'>optional comment</feedback>"` — rate recommendations
```

**Cursor** — add to `.cursorrules`. **Windsurf** — add to your Windsurf rules. The instructions are the same across agents; any AI agent that can execute shell commands can use Spark.

## Privacy

- Only error messages and solutions are shared — no source code
- No files are uploaded — queries are text-only
- Credentials are never transmitted
- Only `spark share` sends data to the network