@lex-inc/thoughtful

Command-line interface for interacting with your Thoughtful workspace.

Installation

bun add -g @lex-inc/thoughtful

Usage

Authentication

# Log in to Thoughtful (interactive - will prompt for email and verification code)
thoughtful login

# Log in non-interactively with email and code
thoughtful login --email [email protected] --code 123456

# Log in in non-interactive mode (requires --email and --code flags)
thoughtful login --no-input --email [email protected] --code 123456

# Show current user, organization, and workspace
thoughtful whoami

# Log out
thoughtful logout

Organizations

# List organizations you belong to
thoughtful orgs list

# Switch to a different organization
thoughtful orgs switch <org-id>

Workspaces

# List workspaces in current organization
thoughtful workspaces list

# Switch to a different workspace
thoughtful workspaces switch <workspace-id>

# Create a new workspace
thoughtful workspaces create "My New Workspace"

Pages

# List all pages (tree view)
thoughtful pages list

# List all pages (flat)
thoughtful pages list --flat

# Get page details
thoughtful pages get <slug>

# Create a new page
thoughtful pages create "Page Title"
thoughtful pages create "Page Title" --parent parent-slug
thoughtful pages create "Page Title" --owner [email protected]
thoughtful pages create "Page Title" --status on_track

# Create a page with title from stdin
echo "Page Title" | thoughtful pages create -
thoughtful pages create - < title.txt

# Update a page
thoughtful pages update <slug> --title "New Title"
thoughtful pages update <slug> --status completed
thoughtful pages update <slug> --owner [email protected]

# Delete a page
thoughtful pages delete <slug>
thoughtful pages delete <slug> --yes  # Skip confirmation

# Search pages
thoughtful pages search "query"

Chat Threads

# List recent chat threads
thoughtful threads list

# Start a new thread
thoughtful threads new
thoughtful threads new "Initial message"

# Show messages in a thread
thoughtful threads show <thread-id>

# Send a message to a thread
thoughtful threads send <thread-id> "Your message"

# Send a message without quotes (variadic args)
thoughtful threads send <thread-id> Your message here

# Send a message from stdin
echo "Your message" | thoughtful threads send <thread-id> -
thoughtful threads send <thread-id> - < message.txt

Shell Completion

The CLI supports tab completion for bash, zsh, and fish shells:

Bash

Add to your ~/.bashrc:

eval "$(thoughtful completion bash)"

Zsh

Add to your ~/.zshrc:

eval "$(thoughtful completion zsh)"

Fish

Save the completion script to your Fish completions directory:

thoughtful completion fish > ~/.config/fish/completions/thoughtful.fish

After adding the completion script, restart your shell or source the config file:

# Bash
source ~/.bashrc

# Zsh
source ~/.zshrc

# Fish - restart the shell or run
source ~/.config/fish/config.fish

Global Flags

The following flags can be used with any command:

• --json: Output results in JSON format (machine-readable)
• --no-color: Disable colored output
• --no-input: Disable interactive prompts (requires all inputs via flags)
• -q, --quiet: Suppress non-essential output
• -v, --verbose: Show verbose output
• --dev: Use development API (http://localhost:3000)
• --prod: Use production API (https://www.thoughtful.app)

# JSON output for machine-readable results
thoughtful whoami --json
thoughtful pages list --json

# Non-interactive mode (useful in scripts and CI/CD)
thoughtful login --no-input --email [email protected] --code 123456
thoughtful pages delete old-page --no-input --yes

# Force production API when running from source
bun run dev pages list --prod

# Use local development API
thoughtful pages list --dev

# Combine flags
thoughtful pages list --json --no-color | jq '.pages'

Configuration

Config File Location

The CLI follows the XDG Base Directory Specification for storing configuration:

• XDG-compliant: $XDG_CONFIG_HOME/thoughtful/config.json (if XDG_CONFIG_HOME is set)
• Default: ~/.config/thoughtful/config.json (if XDG_CONFIG_HOME is not set)
• Legacy: ~/.thoughtful/config.json (automatically migrated to XDG location on first run)

The config file stores authentication credentials and workspace preferences:

{
  "apiUrl": "https://www.thoughtful.app",
  "accessToken": "...",
  "refreshToken": "...",
  "tokenExpiresAt": "...",
  "activeOrgId": "...",
  "activeWorkspaceId": "...",
  "user": {
    "id": "...",
    "email": "...",
    "displayName": "..."
  }
}

Tokens are automatically refreshed before expiry.

Environment Variables

The CLI supports the following environment variables:

• THOUGHTFUL_API_URL: Override the API URL

  export THOUGHTFUL_API_URL=http://localhost:3000
  thoughtful whoami

• NODE_ENV: Set to development to automatically use localhost API

  NODE_ENV=development thoughtful pages list  # Uses http://localhost:3000

• THOUGHTFUL_NO_COLOR: Disable colored output (set to 1 or true)

  THOUGHTFUL_NO_COLOR=1 thoughtful pages list

  Also respects the standard NO_COLOR environment variable (no-color.org).

• THOUGHTFUL_DEBUG: Enable debug logging (set to 1 or true)

  THOUGHTFUL_DEBUG=1 thoughtful login

Environment Detection

The CLI automatically detects whether you're in development or production:

• Development mode (uses http://localhost:3000):

  • When running from source: bun run dev <command>
  • When NODE_ENV=development is set

• Production mode (uses https://www.thoughtful.app):

  • When installed globally: thoughtful <command>
  • When built and run from dist: ./dist/index.js <command>

You can override the environment detection with CLI flags:

# Force production API when running from source
bun run dev pages list --prod

# Force development API when using installed CLI
thoughtful pages list --dev

Configuration Precedence

Settings are resolved in the following order (highest to lowest priority):

1. Command-line flags (e.g., --dev, --prod, --json)
2. Environment variables (e.g., THOUGHTFUL_API_URL, NODE_ENV)
3. Config file (~/.config/thoughtful/config.json)
4. Smart defaults based on environment:
   • Development: http://localhost:3000
   • Production: https://www.thoughtful.app

Development

# Install dependencies
bun install

# Run in development mode
bun run dev <command>

# Build for production
bun run build

# Type check
bun run typecheck

License

MIT