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

# CLI

> Knowledge management from your terminal

The Whilst CLI provides fast, scriptable access to documents, folders, and search directly from your terminal. Zero dependencies, single 32KB binary.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @whilst/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @whilst/cli
  ```

  ```bash npx (no install) theme={null}
  npx @whilst/cli
  ```

  ```bash From source theme={null}
  git clone https://github.com/ibgoldbergs/whilst-slack-bot
  cd whilst-slack-bot/services/whilst-cli
  pnpm install && node build.mjs
  node dist/cli.mjs --version
  ```
</CodeGroup>

**Requirements:** Node.js 20+

## Authentication

Three ways to authenticate, in priority order:

<Steps>
  <Step title="Interactive login (recommended)">
    Run `whilst auth login` and paste your API key when prompted. Credentials are stored securely in `~/.config/whilst/credentials.json` and persist across sessions.

    ```bash theme={null}
    whilst auth login
    ```

    Or pass the key directly:

    ```bash theme={null}
    whilst auth login --api-key whl_live_your_key_here
    ```
  </Step>

  <Step title="Environment variable">
    Set `WHILST_API_KEY` for session-wide access. Add to your shell profile (`~/.bashrc`, `~/.zshrc`) to persist.

    ```bash theme={null}
    export WHILST_API_KEY=whl_live_your_key_here
    ```
  </Step>

  <Step title="Per-command flag">
    Use `--api-key` to override for a single command.

    ```bash theme={null}
    whilst docs list --api-key whl_live_your_key_here
    ```
  </Step>
</Steps>

Get your API key from [Settings → API Keys](https://app.whilst.io/settings/api). Keys start with `whl_live_` (production) or `whl_test_` (testing).

Verify the connection:

```bash theme={null}
whilst auth status
```

<Tip>
  Use `whilst auth login` instead of environment variables — it's simpler and persists automatically.
</Tip>

## Commands

### Auth

```bash theme={null}
whilst auth login                      # Interactive API key prompt
whilst auth login --api-key <key>      # Non-interactive login
whilst auth logout                     # Remove stored credentials
whilst auth status                     # Show auth info and connection status
```

### Documents

<AccordionGroup>
  <Accordion title="whilst docs list" icon="list">
    List documents with optional filtering.

    ```bash theme={null}
    whilst docs list
    whilst docs list --folder-id <uuid>        # filter by folder
    whilst docs list --search "meeting notes"  # full-text search
    whilst docs list --tags "tag1,tag2"        # filter by tags
    whilst docs list --limit 20               # max results (default: 50)
    whilst docs list --pinned                 # only pinned documents
    whilst docs list --fields id,title        # only return specified fields
    ```
  </Accordion>

  <Accordion title="whilst docs get" icon="file">
    Get full document content and metadata.

    ```bash theme={null}
    whilst docs get <document-uuid>
    ```
  </Accordion>

  <Accordion title="whilst docs create" icon="plus">
    Create a document from inline content, a file, or piped stdin.

    ```bash theme={null}
    # From inline markdown
    whilst docs create --content "# Project Plan\n\nObjectives..."

    # From a local file
    whilst docs create --file ./design-doc.md

    # Pipe content from stdin
    echo "# Generated Report" | whilst docs create --folder "Reports"
    cat analysis.md | whilst docs create

    # JSON input mode
    echo '{"content":"# Doc","folder":"Engineering"}' | whilst docs create --json

    # Into a specific folder (by name or UUID)
    whilst docs create --content "# Notes" --folder "Engineering"
    ```

    Content resolution order: `--file` > `--content` > stdin.
  </Accordion>

  <Accordion title="whilst docs update" icon="pen">
    Update specific fields of a document.

    ```bash theme={null}
    whilst docs update <uuid> --title "New Title"
    whilst docs update <uuid> --content "# Revised Content"
    whilst docs update <uuid> --file ./updated.md
    whilst docs update <uuid> --tags "v2,release"
    whilst docs update <uuid> --folder-id <folder-uuid>
    whilst docs update <uuid> --pin
    whilst docs update <uuid> --archive

    # Pipe content for update
    echo "# Revised" | whilst docs update <uuid>
    ```
  </Accordion>

  <Accordion title="whilst docs delete / move" icon="ellipsis">
    ```bash theme={null}
    # Delete (requires --yes confirmation)
    whilst docs delete <uuid> --yes

    # Move to a folder
    whilst docs move <uuid> --folder-id <folder-uuid>
    whilst docs move <uuid> --folder-id null   # move to root
    ```
  </Accordion>
</AccordionGroup>

### Folders

<AccordionGroup>
  <Accordion title="whilst folders list / get" icon="folder">
    ```bash theme={null}
    whilst folders list
    whilst folders list --parent-id <uuid>     # children of a folder
    whilst folders list --include-counts       # include doc counts
    whilst folders get <uuid>
    ```
  </Accordion>

  <Accordion title="whilst folders create / update" icon="folder-plus">
    ```bash theme={null}
    whilst folders create "Project Alpha"
    whilst folders create "Subfolder" --parent-id <uuid>
    whilst folders create "Notes" --description "Team notes"

    whilst folders update <uuid> --name "New Name"
    whilst folders update <uuid> --description "Updated"
    ```
  </Accordion>

  <Accordion title="whilst folders tree" icon="sitemap">
    View the full folder hierarchy.

    ```bash theme={null}
    whilst folders tree                        # full hierarchy
    whilst folders tree --depth 3              # limit depth
    whilst folders tree --include-counts       # show doc counts
    whilst folders tree <folder-uuid>          # tree from specific root
    ```

    Table output:

    ```
    ├── Engineering/
    │   ├── Frontend/  (12 docs)
    │   └── Backend/  (8 docs)
    └── Marketing/  (3 docs)
    ```
  </Accordion>

  <Accordion title="whilst folders delete / move" icon="ellipsis">
    ```bash theme={null}
    whilst folders delete <uuid> --yes                # fails if non-empty
    whilst folders delete <uuid> --cascade --yes      # deletes folder AND contents
    whilst folders move <uuid> --parent-id <uuid>
    whilst folders move <uuid> --parent-id null       # move to root
    ```
  </Accordion>
</AccordionGroup>

### Search

```bash theme={null}
# Hybrid search (keyword + semantic)
whilst search "API design patterns"
whilst search "onboarding" --mode balanced          # 50/50 (default)
whilst search "auth flow" --mode keyword            # keyword-weighted
whilst search "conceptual overview" --mode semantic # semantic-weighted
whilst search "meeting" --folder-id <uuid>          # scope to folder
whilst search "query" --limit 10

# Find similar documents
whilst search similar <document-uuid>
```

### Web Search

Search the web for current information with AI-synthesized answers and citations.

```bash theme={null}
whilst web-search "latest React 19 patterns"
whilst web-search "OpenAI API pricing 2026" --context "comparing with Anthropic"
```

### Bulk Operations

```bash theme={null}
# Move multiple documents
whilst bulk move --ids "uuid1,uuid2,uuid3" --folder-id <folder-uuid>

# Delete multiple documents
whilst bulk delete --ids "uuid1,uuid2,uuid3" --yes

# Tag multiple documents
whilst bulk tag --ids "uuid1,uuid2,uuid3" --tag "reviewed"

# Change visibility
whilst bulk visibility --ids "uuid1,uuid2,uuid3" --visibility workspace

# JSON input mode
echo '{"ids":["id1","id2"],"folder_id":"<uuid>"}' | whilst bulk move --json
```

### Status

```bash theme={null}
whilst status
```

Returns connection status and CLI version. Use to verify your API key is valid.

## Output Formats

All commands support multiple output formats:

```bash theme={null}
whilst docs list                       # JSON (default, ideal for scripting)
whilst docs list -t                    # Human-readable table with colors
whilst docs list -q                    # Quiet (just IDs)
whilst docs list --fields id,title     # Only specified fields
```

<Info>
  Data goes to **stdout**, errors go to **stderr** — safe for piping. Colors are automatically disabled when output is piped or the `NO_COLOR` environment variable is set.
</Info>

## Scripting & Piping

The CLI is designed for scripting and automation:

```bash theme={null}
# Create a folder and add documents
FOLDER_ID=$(whilst folders create "Q1 Planning" -q)
whilst docs create --file ./roadmap.md --folder "$FOLDER_ID"

# Search, extract IDs, bulk move
RESULTS=$(whilst search "onboarding")
IDS=$(echo "$RESULTS" | jq -r '[.results[].id] | join(",")')
whilst bulk move --ids "$IDS" --folder-id <folder-uuid>

# Pipe generated content
python generate_report.py | whilst docs create --folder "Reports"

# Export all docs in a folder
DOC_IDS=$(whilst docs list --folder-id <uuid> -q)
for ID in $DOC_IDS; do
  whilst docs get "$ID" | jq -r '.content' > "${ID}.html"
done
```

## Environment Variables

| Variable          | Description                                       |
| ----------------- | ------------------------------------------------- |
| `WHILST_API_KEY`  | Your API key (alternative to `whilst auth login`) |
| `WHILST_ENDPOINT` | Custom API endpoint (optional, for self-hosted)   |
| `WHILST_CONFIRM`  | Set to `true` to skip `--yes` on deletions        |
| `WHILST_VERBOSE`  | Set to `1` for verbose HTTP logging               |
| `NO_COLOR`        | Set to disable colored output                     |

## Exit Codes

| Code | Meaning                     |
| ---- | --------------------------- |
| 0    | Success                     |
| 2    | Usage error (bad arguments) |
| 3    | Authentication error        |
| 4    | Not found                   |
| 5    | Permission denied           |
| 6    | Validation error            |
| 7    | Network error               |

```bash theme={null}
whilst docs get <uuid>
case $? in
  0) echo "Success" ;;
  3) echo "Bad API key" ;;
  4) echo "Document not found" ;;
  7) echo "Network issue, retry later" ;;
esac
```

## Global Options

```bash theme={null}
--format <json|table|quiet>   # Output format (default: json)
-t                            # Shorthand for --format table
-q                            # Shorthand for --format quiet
--fields <f1,f2,...>          # Only include specified fields
--api-key <key>               # Use a specific API key for this command
--verbose, -V                 # Verbose logging to stderr
--help, -h                    # Show help
--version, -v                 # Show version
```

## UX Features

The CLI includes several quality-of-life features:

* **Colors** — Table output uses colored headers, IDs, and dates for readability. Automatically disabled in non-TTY environments or when `NO_COLOR` is set.
* **Spinners** — Network requests show a spinner on stderr so you know the CLI is working.
* **Did-you-mean** — Mistyped commands get helpful suggestions (e.g., `whilst dcs list` → "Did you mean docs?").
* **Actionable errors** — Error messages include what to do next, not just what went wrong.