CLI

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

Installation

npm install -g @whilst/cli

pnpm add -g @whilst/cli

npx @whilst/cli

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

Requirements: Node.js 20+

Authentication

Three ways to authenticate, in priority order:

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.

whilst auth login

Or pass the key directly:

whilst auth login --api-key whl_live_your_key_here

Environment variable

Set WHILST_API_KEY for session-wide access. Add to your shell profile (~/.bashrc, ~/.zshrc) to persist.

export WHILST_API_KEY=whl_live_your_key_here

Per-command flag

Use --api-key to override for a single command.

whilst docs list --api-key whl_live_your_key_here

Get your API key from Settings → API Keys. Keys start with whl_live_ (production) or whl_test_ (testing). Verify the connection:

whilst auth status

Use whilst auth login instead of environment variables — it’s simpler and persists automatically.

Commands

Auth

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

whilst docs list

List documents with optional filtering.

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

whilst docs get

Get full document content and metadata.

whilst docs get <document-uuid>

whilst docs create

Create a document from inline content, a file, or piped stdin.

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

whilst docs update

Update specific fields of a document.

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>

whilst docs delete / move

# 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

Folders

whilst folders list / get

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>

whilst folders create / update

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"

whilst folders tree

View the full folder hierarchy.

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)

whilst folders delete / move

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

Search

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

whilst web-search "latest React 19 patterns"
whilst web-search "OpenAI API pricing 2026" --context "comparing with Anthropic"

Bulk Operations

# 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

whilst status

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

Output Formats

All commands support multiple output formats:

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

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.

Scripting & Piping

The CLI is designed for scripting and automation:

# 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

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

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

Getting Started

Features

Guides

Development

Installation

Authentication

Commands

Auth

Documents

Folders

Search

Web Search

Bulk Operations

Status

Output Formats

Scripting & Piping

Environment Variables

Exit Codes

Global Options

UX Features

​Installation

​Authentication

​Commands

​Auth

​Documents

​Folders

​Search

​Web Search

​Bulk Operations

​Status

​Output Formats

​Scripting & Piping

​Environment Variables

​Exit Codes

​Global Options

​UX Features

Installation

Authentication

Commands

Auth

Documents

Folders

Search

Web Search

Bulk Operations

Status

Output Formats

Scripting & Piping

Environment Variables

Exit Codes

Global Options

UX Features