npm package: @lex-inc/thoughtful
Description: CLI tool for interacting with your Thoughtful workspace
Author: Thoughtful Inc.
Latest version: 0.0.4

# @lex-inc/thoughtful

Command-line interface for interacting with your Thoughtful workspace.

## Installation

```bash
bun add -g @lex-inc/thoughtful
```

## Usage

### Authentication

```bash
# 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 user@example.com --code 123456

# Log in in non-interactive mode (requires --email and --code flags)
thoughtful login --no-input --email user@example.com --code 123456

# Show current user, organization, and workspace
thoughtful whoami

# Log out
thoughtful logout
```

### Organizations

```bash
# List organizations you belong to
thoughtful orgs list

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

### Workspaces

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

```bash
# 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 user@example.com
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 user@example.com

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

# Search pages
thoughtful pages search "query"
```

### Chat Threads

```bash
# 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`:

```bash
eval "$(thoughtful completion bash)"
```

#### Zsh

Add to your `~/.zshrc`:

```bash
eval "$(thoughtful completion zsh)"
```

#### Fish

Save the completion script to your Fish completions directory:

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

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

```bash
# 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)

```bash
# 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 user@example.com --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](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) 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:

```json
{
  "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
  ```bash
  export THOUGHTFUL_API_URL=http://localhost:3000
  thoughtful whoami
  ```

- **`NODE_ENV`**: Set to `development` to automatically use localhost API
  ```bash
  NODE_ENV=development thoughtful pages list  # Uses http://localhost:3000
  ```

- **`THOUGHTFUL_NO_COLOR`**: Disable colored output (set to `1` or `true`)
  ```bash
  THOUGHTFUL_NO_COLOR=1 thoughtful pages list
  ```

  Also respects the standard `NO_COLOR` environment variable ([no-color.org](https://no-color.org/)).

- **`THOUGHTFUL_DEBUG`**: Enable debug logging (set to `1` or `true`)
  ```bash
  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:

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

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