Skip to main content
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
Requirements: Node.js 20+

​
Authentication

Three ways to authenticate, in priority order:
1

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
2

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
3

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

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
Get full document content and metadata.
whilst docs get <document-uuid>
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.
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>

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

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

VariableDescription
WHILST_API_KEYYour API key (alternative to whilst auth login)
WHILST_ENDPOINTCustom API endpoint (optional, for self-hosted)
WHILST_CONFIRMSet to true to skip --yes on deletions
WHILST_VERBOSESet to 1 for verbose HTTP logging
NO_COLORSet to disable colored output

​
Exit Codes

CodeMeaning
0Success
2Usage error (bad arguments)
3Authentication error
4Not found
5Permission denied
6Validation error
7Network 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.