CLI reference

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

npx shareful-ai <command> [options]

Commands

`init`

Create a new shares repository.

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:

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

`create`

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

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:

npx shareful-ai create

Prompts you for each field with validation.

Non-interactive mode:

Pass all four flags to skip prompts:

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.

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:

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

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.

npx shareful-ai skills

`--help`

Display help information.

npx shareful-ai --help

`--version`

Display the current version.

npx shareful-ai --version

Telemetry

The CLI collects anonymous, non-identifying usage events. Set DISABLE_TELEMETRY=1 to opt out. See configuration for details.

Next steps

Share format specification -- field constraints and validation rules
Creating shares -- writing tips and quality standards
Configuration -- settings and environment variables

On this page