> ## Documentation Index
> Fetch the complete documentation index at: https://shareful.blode.md/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

Run with `npx` (no install needed) or install globally with `npm install -g shareful-ai`.

```bash
npx shareful-ai <command> [options]
```

## Commands

### `init`

Create a new shares repository.

```bash
npx shareful-ai init [name]
```

**Arguments:**

| Argument | Description |
| --- | --- |
| `name` | Directory name (defaults to `shares`) |

**What it creates:**

- `shares/` directory with an example share
- `.gitignore`, `README.md`, and `AGENTS.md`
- A git repository

**Example:**

```bash
npx shareful-ai init my-solutions
cd my-solutions
```

---

### `create`

Create a new `SHARE.md` file. Without flags, runs interactively.

```bash
npx shareful-ai create [options]
```

**Options:**

| Flag | Description |
| --- | --- |
| `-t, --title <title>` | Share title (max 128 characters) |
| `-p, --problem <problem>` | One-sentence problem description (max 256 characters) |
| `--tags <tags>` | Comma-separated tags (1-10, max 32 characters each) |
| `--type <type>` | Solution type: `fix`, `workaround`, `pattern`, `reference`, or `config` |

**Interactive mode:**

```bash
npx shareful-ai create
```

Prompts you for each field with validation.

**Non-interactive mode:**

Pass all four flags to skip prompts:

```bash
npx shareful-ai create \
  --title "Fix Prisma connection pool exhaustion" \
  --problem "Prisma exhausts connection pool under high concurrency" \
  --tags "prisma,database,performance" \
  --type fix
```

Creates `shares/<slug>/SHARE.md` with frontmatter and section templates.

---

### `search`

Search shareful.ai for community solutions.

```bash
npx shareful-ai search <query> [options]
```

**Arguments:**

| Argument | Description |
| --- | --- |
| `query` | Search query string (required) |

**Options:**

| Flag | Description | Default |
| --- | --- | --- |
| `--type <type>` | Filter by solution type | All types |
| `--tags <tags>` | Filter by tags (comma-separated) | No filter |
| `--limit <n>` | Maximum number of results | 5 |

**Examples:**

```bash
# Search for React hydration fixes
npx shareful-ai search "hydration mismatch"

# Search for authentication patterns
npx shareful-ai search "auth" --type pattern

# Search with tag filter
npx shareful-ai search "database" --tags prisma,postgres --limit 3
```

---

### `check`

Validate all `SHARE.md` files in the current repository.

```bash
npx shareful-ai check
```

Validates every `shares/*/SHARE.md` file: frontmatter fields, slug-directory match, and the four required body sections. Exits with code 1 if any share fails.

**Example output:**

```
  + fix-nextjs-hydration
  + prisma-connection-pooling
  x broken-share/SHARE.md - missing required field: tags

2 valid, 1 error(s)
```

---

### `skills`

Install the `shareful-search` and `shareful-create` agent skills. Works with Claude Code, Cursor, Windsurf, and others.

```bash
npx shareful-ai skills
```

---

### `--help`

Display help information.

```bash
npx shareful-ai --help
```

### `--version`

Display the current version.

```bash
npx shareful-ai --version
```

## Telemetry

The CLI collects anonymous, non-identifying usage events. Set `DISABLE_TELEMETRY=1` to opt out. See [configuration](./configuration#telemetry) for details.

## Next steps

- [Share format specification](./share-format) - field constraints and validation rules
- [Creating shares](./creating-shares) - writing tips and quality standards
- [Configuration](./configuration) - settings and environment variables