Assay CLI

Command-line interface for Assay document library.

Installation

npm install -g assay-cli

Or install from source:

cd assay-cli
npm install
npm run build
npm link

Quick Start

1. Authenticate:

   assay auth login

   This opens your browser to the Dashboard where you can generate an API key. Paste the key when prompted.

2. Check status:

   assay auth status

3. List documents:

   assay documents list

4. Search documents:

   assay documents search --query "AI safety"

Commands

Authentication

• assay auth login - Authenticate and generate API key
• assay auth status - Show API key status and quota information
• assay auth rotate - Rotate API key (opens Dashboard)

Documents

• assay documents list - List documents with pagination
  • --filter <type> - Document filter: public (all public docs), personal (your docs), or private (your private docs only). Default: public
  • --visibility <type> - [DEPRECATED] Use --filter instead. Filter by visibility (private, public, all)
  • --limit <number> - Maximum results per page
  • --cursor <cursor> - Pagination cursor
• assay documents get <id> - Get document details
• assay documents summary <id> - Get document summary
  • --type <type> - Summary type: comprehensive, casual, or faq. Default: comprehensive
• assay documents search - Search documents
  • --query <query> - General search query
  • --theme <theme> - Canonical theme ID or partial match
  • --author <author> - Author name
  • --title <title> - Document title
  • --keywords <keywords> - Keywords or concepts
  • --filter <type> - Document filter: public (all public docs), personal (your docs), or private (your private docs only). Default: public
  • --visibility <type> - [DEPRECATED] Use --filter instead. Document visibility filter
  • --limit <number> - Maximum results

Themes

• assay themes list - Browse canonical themes
  • --domain <domain> - L0 domain ID (returns L1 themes for that domain)

Configuration

Configuration is stored in:

• Unix/macOS: ~/.assay/config.json
• Windows: %APPDATA%\assay\config.json

API keys are stored securely in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service).

If keychain is unavailable (e.g., headless Linux), you can:

• Set ASSAY_API_KEY environment variable
• Or use the config file with secure permissions (chmod 600)

Environment Variables

• ASSAY_API_KEY - API key (overrides config)
• ASSAY_BASE_URL - Base URL (overrides config)
• ASSAY_CONFIG_DIR - Config directory (overrides default)

Output Formats

Set output format in config or use --format option:

• json (default) - JSON output
• table - Table format
• yaml - YAML output

Error Handling

The CLI automatically:

• Retries on rate limit errors (429) with exponential backoff
• Shows expiration warnings when API key expires soon
• Provides helpful error messages with suggestions

Examples

# List all public documents (default)
assay documents list

# List your documents (public + private)
assay documents list --filter personal

# List only your private documents
assay documents list --filter private

# Search for documents about AI safety in public collection
assay documents search --query "AI safety" --filter public --limit 10

# Search in your documents
assay documents search --query "AI safety" --filter personal

# Get a specific document
assay documents get abc123

# Get document summary
assay documents summary abc123 --type casual

# Browse themes
assay themes list

# List L1 themes for a domain
assay themes list --domain ARTIFICIAL_INTELLIGENCE

Troubleshooting

"No API key found"

• Run assay auth login to authenticate

"API key expired"

• Run assay auth login to generate a new key

"Keychain not available"

• Set ASSAY_API_KEY environment variable
• Or ensure Secret Service is installed (Linux)

"Rate limit exceeded"

• Wait for quota reset (shown in error message)
• Check quota with assay auth status