Installation

Requires Node.js 20+ (see the uselab package engines field).

pnpm add -g uselab

Or run directly without installation:

pnpm dlx uselab@latest --help

Quick Start

1. Initialize your project:

   pnpmnpmyarnbun

   pnpm dlx uselab@latest init
   

   Copy

2. Install a hook:

   pnpmnpmyarnbun

   pnpm dlx uselab@latest add use-network-status
   

   Copy

3. View available hooks:

   pnpmnpmyarnbun

   pnpm dlx uselab@latest list
   

   Copy

Commands at a glance: add (install hooks), init (project config), view (inspect before install), list / search (discover hooks), build (compile a local registry JSON into per-hook JSON files for publishing or tooling).

Commands

add - Install Hooks

Install one or more hooks from the registry, URL, or local file path.

Syntax

pnpm dlx uselab@latest add [options] [hooks...]

Arguments

• [hooks...] - Hook name(s), URL(s), or local path(s) (space-separated)

  • Registry names: Accepts kebab-case or camelCase format

    • Examples: use-network-status, useToggle, useCounter

  • URLs: Full URL to a hook JSON file

    • Examples: https://example.com/hooks/use-custom.json

  • Local paths: Relative or absolute path to a local hook JSON file

    • Examples: ./hooks/use-custom.json, ../shared/use-utils.json

Options

Do not pass --js and --ts together; the CLI will error if both are set.

Examples

Install a single hook:

pnpm dlx uselab@latest add use-network-status

pnpm dlx uselab@latest add useToggle

pnpm dlx uselab@latest add use-counter

Install multiple hooks:

pnpm dlx uselab@latest add use-counter use-toggle use-network-status

pnpm dlx uselab@latest add useBattery useCounter useToggle

Skip confirmation prompts:

pnpm dlx uselab@latest add use-counter --yes

pnpm dlx uselab@latest add use-toggle -y

Overwrite existing files:

pnpm dlx uselab@latest add use-network-status --overwrite

pnpm dlx uselab@latest add use-counter --overwrite --yes

Specify working directory:

pnpm dlx uselab@latest add use-toggle --cwd /path/to/project

pnpm dlx uselab@latest add use-counter -c ./my-project

Custom installation path:

pnpm dlx uselab@latest add use-counter --path src/custom/hooks

pnpm dlx uselab@latest add use-toggle -p lib/hooks

Force JavaScript or TypeScript variant (when the registry item ships both):

pnpm dlx uselab@latest add use-counter --js

pnpm dlx uselab@latest add use-counter --ts

Install from URL:

pnpm dlx uselab@latest add https://example.com/hooks/use-custom.json

pnpm dlx uselab@latest add https://cdn.example.com/hooks/use-utils.json

Install from local file:

pnpm dlx uselab@latest add ./local-hooks/use-custom.json

pnpm dlx uselab@latest add ../shared-hooks/use-utils.json

pnpm dlx uselab@latest add /absolute/path/to/hook.json

Combined options:

pnpm dlx uselab@latest add use-counter use-toggle --yes --path src/hooks

pnpm dlx uselab@latest add use-network-status --overwrite --cwd ./project

Notes

• URLs and local paths must point to valid JSON files matching the registry hook format
• Multiple hooks are installed sequentially with progress tracking
• Running add without arguments displays usage instructions and examples
• The --yes flag automatically overwrites existing files without prompting
• For registry hooks with TypeScript and JavaScript variants, the CLI chooses a variant from your project by default; use --js or --ts to override

init - Initialize Project

Initialize uselab configuration in your project by creating a uselab.json file.

Syntax

pnpm dlx uselab@latest init [options]

Options

Examples

Initialize in current directory:

pnpm dlx uselab@latest init

Initialize in specific directory:

pnpm dlx uselab@latest init --cwd /path/to/project

pnpm dlx uselab@latest init -c ./my-project

Output

Creates a uselab.json file in your project root:

{
  "hooks": "src/hooks"
}

If the project is already initialized (hooks is already set in uselab.json), the CLI prints a short message and leaves the config unchanged.

view - Preview Hook Details

View detailed information about hook(s) before installing, including code preview, dependencies, and file structure.

Syntax

pnpm dlx uselab@latest view [options] [hooks...]

Arguments

• [hooks...] - Hook name(s) to view (space-separated, optional)

  • Shows usage help if omitted

  • Accepts kebab-case or camelCase format

Options

Examples

View a single hook:

pnpm dlx uselab@latest view use-network-status

pnpm dlx uselab@latest view useToggle

pnpm dlx uselab@latest view use-counter

View multiple hooks:

pnpm dlx uselab@latest view use-counter use-toggle

pnpm dlx uselab@latest view use-network-status useBattery useCounter

View as JSON:

pnpm dlx uselab@latest view use-network-status --format json

pnpm dlx uselab@latest view use-counter --format json

View multiple hooks as JSON:

pnpm dlx uselab@latest view use-counter use-toggle --format json

Output Format

Code format (default):

• Human-readable format with syntax highlighting
• Shows code preview, dependencies, dev dependencies, registry dependencies (when present), and file paths (including [ts] / [js] labels for variant hooks)
• Displays installation instructions

JSON format:

• Complete hook data as JSON
• Includes all hook metadata and file contents
• Useful for programmatic access or integration

list - List Available Hooks

List all available hooks from the UseKit registry with filtering and pagination support.

Syntax

pnpm dlx uselab@latest list [options]

Options

Examples

List all hooks:

pnpm dlx uselab@latest list

Filter by query:

pnpm dlx uselab@latest list --query network

pnpm dlx uselab@latest list -q "state management"

pnpm dlx uselab@latest list --query counter

Limit results:

pnpm dlx uselab@latest list --limit 20

pnpm dlx uselab@latest list -l 50

Pagination:

pnpm dlx uselab@latest list --offset 10

pnpm dlx uselab@latest list --limit 20 --offset 10

pnpm dlx uselab@latest list -l 10 -o 20

Filter with pagination:

pnpm dlx uselab@latest list --query network --limit 10 --offset 10

pnpm dlx uselab@latest list -q network -l 20 -o 0

Show all results (ignore pagination):

pnpm dlx uselab@latest list --skip-limit

pnpm dlx uselab@latest list --query network --skip-limit

pnpm dlx uselab@latest list -q "state" --skip-limit

JSON output:

pnpm dlx uselab@latest list --format json

pnpm dlx uselab@latest list --format json --limit 10

pnpm dlx uselab@latest list -q network --format json

Combined options:

pnpm dlx uselab@latest list --query network --limit 20 --offset 10 --format json

pnpm dlx uselab@latest list -q counter --skip-limit --format json

Output Format

Table format (default):

• Human-readable list with hook names, titles, and descriptions
• Shows pagination information
• Displays total count and current range

JSON format:

• Array of hook objects with only essential fields:

  [
    {
      "name": "use-network-status",
      "title": "Use Network Status",
      "description": "Monitor network status..."
    }
  ]

  Copy

search - Search Hooks

Search for hooks in the registry with the same filtering and pagination behavior as list, with an optional positional query for quick typing.

Syntax

pnpm dlx uselab@latest search [options] [query]

Arguments

• [query] - Optional search string. Equivalent to -q, --query when used alone. If you pass both, the --query value takes precedence.

Options

Examples

Search all hooks:

pnpm dlx uselab@latest search

Search with query:

pnpm dlx uselab@latest search network

pnpm dlx uselab@latest search -q network

pnpm dlx uselab@latest search --query "state management"

Limit search results:

pnpm dlx uselab@latest search --limit 10

pnpm dlx uselab@latest search -l 20

pnpm dlx uselab@latest search network --limit 5

Pagination:

pnpm dlx uselab@latest search --offset 10

pnpm dlx uselab@latest search --limit 20 --offset 10

pnpm dlx uselab@latest search network -l 10 -o 5

Filter with pagination:

pnpm dlx uselab@latest search --query network --limit 20 --offset 10

pnpm dlx uselab@latest search -q "state" -l 15 -o 0

Show all results (ignore pagination):

pnpm dlx uselab@latest search --skip-limit

pnpm dlx uselab@latest search network --skip-limit

pnpm dlx uselab@latest search -q "state management" --skip-limit

Combined options:

pnpm dlx uselab@latest search --query network --limit 20 --offset 10

pnpm dlx uselab@latest search -q counter --skip-limit

Differences from list

• Both match hooks by substring on name, title, and description; if nothing matches, both can show a short list of similar hook names (ranked for typos)
• list supports --format json; search is interactive table output only
• search accepts an optional positional query (search network) as well as -q / --query

build - Build registry hook JSON

For registry authors: read a registry JSON file (with an items array), load each hook’s source files from disk, embed file contents, and emit one JSON file per hook under an output directory. TypeScript sources are transpiled to JavaScript when building ts/js variants (using the TypeScript compiler API).

Syntax

pnpm dlx uselab@latest build [options]

Options

Examples

pnpm dlx uselab@latest build --registry registry.json --output dist/hooks

pnpm dlx uselab@latest build -r registry.json -o dist --cwd /path/to/project

Behavior

• Skips items that have no files array (with a warning)
• Writes each built hook as {name}.json with embedded files (including variants with content when applicable)
• Sets $schema to https://usekit.vercel.app/schema/registry-item.json on each output file

Global Options

Available for all commands:

Examples

pnpm dlx uselab@latest --version

pnpm dlx uselab@latest --help

pnpm dlx uselab@latest add --help

pnpm dlx uselab@latest list --help

pnpm dlx uselab@latest build --help

Configuration

The CLI creates a uselab.json file in your project root when you run init:

{
  "hooks": "src/hooks"
}

Hooks Directory

By default, hooks are installed to:

• src/hooks/ if a src directory exists
• hooks/ in the project root otherwise

You can customize this in the uselab.json configuration file, or use the --path option when installing hooks.

Configuration Options

Hook Sources

The add command supports three types of hook sources:

1. Registry Hooks

Install hooks from the official UseKit registry:

pnpm dlx uselab@latest add use-network-status

pnpm dlx uselab@latest add useToggle

2. URL Hooks

Install hooks from a remote URL:

pnpm dlx uselab@latest add https://example.com/hooks/use-custom.json

pnpm dlx uselab@latest add https://cdn.example.com/hooks/use-utils.json

Requirements:

• URL must point to a valid JSON file
• JSON must match the registry hook format
• File must be accessible via HTTP/HTTPS

3. Local File Hooks

Install hooks from a local file path:

pnpm dlx uselab@latest add ./local-hooks/use-custom.json

pnpm dlx uselab@latest add ../shared-hooks/use-utils.json

pnpm dlx uselab@latest add /absolute/path/to/hook.json

Requirements:

• Path must point to a valid JSON file
• JSON must match the registry hook format
• File must be readable

Available Hooks

Visit hooks to browse all available hooks.

You can also use the CLI to explore:

List all hooks

pnpm dlx uselab@latest list

Search for hooks

pnpm dlx uselab@latest search network

View hook details

pnpm dlx uselab@latest view use-network-status