npm package: @projectassistant/localdocs
Description: CLI tool for LocalDocs - interact with your team's documentation library from Claude Code
Author: Project Assistant Team
Latest version: 1.4.5

# LocalDocs CLI

Command-line interface for interacting with LocalDocs documentation library from Claude Code.

## Features

- 🔍 **Search** - Search your team's documentation library
- 📥 **Export** - Export documentation to project directories
- ➕ **Add** - Add new documentation URLs
- 🔐 **OAuth Device Flow** - Seamless authentication like Claude Code
- 🤖 **Claude Code Integration** - Use via `/localdocs-search` command
- 🔒 **Secure** - 30-day access tokens with immediate revocation

## Installation

```bash
cd cli
npm install
chmod +x localdocs-cli.js
```

## One-Time Setup

### Authenticate Using Device Flow

```bash
export LOCALDOCS_API_URL="http://localhost:54321"  # Or your production URL
export LOCALDOCS_ANON_KEY="your-anon-key"
node localdocs-cli.js login
```

The CLI will display:

```
🔐 Device Authorization Required
──────────────────────────────────────────────────
📋 Please complete the following steps:

  1. Visit: http://localhost:8085/cli-auth
  2. Enter code: ABC-123
  3. Click "Approve" to authorize this device

Code expires in 10 minutes
──────────────────────────────────────────────────

⠙ Waiting for authorization...
```

Visit the URL, enter the code, and click "Approve". The CLI will automatically receive your access token and save it to `~/.localdocs-cli/config.json`.

**Benefits:**
- No manual token extraction from DevTools
- Seamless authentication like Claude Code
- 30-day access tokens (no weekly re-auth)
- Immediate revocation when users are removed from Bitbucket

## Usage

### Search Documentation

```bash
# Basic search
node localdocs-cli.js search "React hooks"

# Filter by tags
node localdocs-cli.js search "deployment" --tags fastapi,docker

# Limit results
node localdocs-cli.js search "MUI components" --limit 20

# Claude-optimized format
node localdocs-cli.js search "authentication" --format claude
```

### Export Documentation

```bash
# Export by tags
node localdocs-cli.js export --tags react,typescript --output ./docs/localdocs/react

# Export specific documents
node localdocs-cli.js export --ids doc-id-1,doc-id-2 --output ./docs

# Different formats
node localdocs-cli.js export --tags fastapi --format markdown
```

### Add Documentation

```bash
# Add with metadata
node localdocs-cli.js add "https://docs.example.com" \
  --name "Example Framework Docs" \
  --description "Official documentation" \
  --tags example,framework,api

# Simple add
node localdocs-cli.js add "https://mui.com/material-ui/getting-started/"
```

### Check Status

```bash
node localdocs-cli.js status
```

## Claude Code Integration

### Using the `/localdocs-search` Command

In any Claude Code session:

```
/localdocs-search "React documentation"
```

Claude Code will:
1. Search your team's LocalDocs library
2. Display results
3. Offer to export matching docs to your project

### Direct CLI Usage from Claude

You can also ask Claude to run CLI commands directly:

```
User: "Search our team's FastAPI documentation and export it to docs/localdocs/fastapi/"

Claude: [Runs]
  node cli/localdocs-cli.js search "FastAPI" --tags fastapi --format claude
  node cli/localdocs-cli.js export --tags fastapi --output docs/localdocs/fastapi/
```

## Configuration

Config file location: `~/.localdocs-cli/config.json`

```json
{
  "supabase_url": "https://your-project.supabase.co",
  "jwt_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "updated_at": "2025-10-10T12:00:00.000Z"
}
```

## Token Refresh

Access tokens expire after 30 days. When you see authentication errors:

```bash
# Simply re-run the device flow login
node localdocs-cli.js login
```

The device flow will guide you through re-authorization. If your account has been disabled or you've been removed from Bitbucket, your tokens will be immediately revoked.

## Environment Variables

- `LOCALDOCS_API_URL` - Your Supabase project URL (required)

Set in `.env`:
```bash
LOCALDOCS_API_URL=https://your-project.supabase.co
```

## Troubleshooting

### "Not authenticated" Error

Run `node localdocs-cli.js login --token <token>` to authenticate.

### "LOCALDOCS_API_URL not configured"

Set the environment variable:
```bash
export LOCALDOCS_API_URL="https://your-project.supabase.co"
```

### "Failed to add document"

Check that:
1. URL is valid and accessible
2. You're authenticated (`node localdocs-cli.js status`)
3. You have permissions in LocalDocs

### Token Expired

Re-login with a fresh token from the browser.

## Development

```bash
# Install dependencies
cd cli
npm install

# Test commands
node localdocs-cli.js --help
node localdocs-cli.js search --help
```

## Architecture

```
┌─────────────────┐
│  Claude Code    │
│  /localdocs-*   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ localdocs-cli.js│ (This tool)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Supabase Edge   │
│ Functions       │
│ - search docs   │
│ - export docs   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ PostgreSQL DB   │
│ (Team Docs)     │
└─────────────────┘
```

## Security

- JWT tokens are stored in `~/.localdocs-cli/config.json` (mode 600)
- All API calls use HTTPS
- Tokens should be rotated regularly
- Never commit config.json to version control

## MCP Integration for Claude Code

Install LocalDocs as an MCP server for Claude Code:

```bash
claude mcp add localdocs -- npx --package=@projectassistant/localdocs -y localdocs-mcp
```

### Usage with Claude Code

Once installed, you can use natural language with Claude:

- "Search our LocalDocs for React documentation"
- "Export our FastAPI docs to this project"
- "Add the Supabase documentation to our team library"

Claude Code will automatically use the LocalDocs MCP tools.

### Authentication

Authenticate once using the CLI:

```bash
npx @projectassistant/localdocs login
```

The MCP server will use the same authentication (valid for 30 days).

## License

MIT