@tfl-inc/cli 0.0.1

package/ENVIRONMENT.md

@@ -0,0 +1,83 @@
+# Environment Configuration
+
+The CLI now supports automatic environment detection and manual environment control via flags.
+
+## Automatic Environment Detection
+
+The CLI automatically detects whether it's running in development or production:
+
+### Development Mode (uses `http://localhost:3000`)
+- When running from source via `bun run dev`
+- When `NODE_ENV=development` is set
+
+### Production Mode (uses `https://www.tokatsu.ai`)
+- When installed globally via `npm install -g @tfl-inc/cli`
+- When running the built CLI from `dist/index.js`
+
+## Manual Environment Control
+
+You can override the automatic detection with command-line flags:
+
+```bash
+# Force development API (localhost:3000)
+thoughtful pages list --dev
+
+# Force production API (www.tokatsu.ai)
+bun run dev pages list --prod
+```
+
+## Configuration Precedence
+
+API URL is determined in this order (highest to lowest priority):
+
+1. **CLI flags**: `--dev` or `--prod`
+2. **Environment variable**: `THOUGHTFUL_API_URL`
+3. **Config file**: `~/.config/thoughtful/config.json`
+4. **Smart default**:
+   - `http://localhost:3000` when running from source
+   - `https://www.tokatsu.ai` when running built/installed CLI
+
+## Important Implementation Details
+
+### Config File Preservation
+
+The CLI prevents environment/flag-based overrides from being persisted to the config file. This means:
+
+- Using `--dev` or `--prod` flags won't change your config file
+- Using `THOUGHTFUL_API_URL` won't change your config file
+- Token refreshes preserve your config file's API URL
+
+Only explicit user actions (like `thoughtful config set-url`) would change the stored API URL.
+
+### Examples
+
+```bash
+# Development workflow
+bun run dev pages list                           # Uses config file URL
+bun run dev pages list --dev                     # Forces localhost
+THOUGHTFUL_API_URL=http://localhost:3000 bun run dev pages list  # Uses env var
+
+# Production workflow
+thoughtful pages list                            # Uses production
+thoughtful pages list --dev                      # Forces localhost for testing
+
+# Override examples
+NODE_ENV=development thoughtful pages list       # Uses localhost
+THOUGHTFUL_API_URL=https://staging.example.com thoughtful pages list  # Uses staging
+```
+
+## Testing
+
+To verify the configuration is working:
+
+```bash
+# Check current config
+cat ~/.config/thoughtful/config.json | jq -r '.apiUrl'
+
+# Test with different environments
+bun run dev whoami --prod    # Should connect to production
+bun run dev whoami --dev     # Should try localhost (will fail if server not running)
+
+# Verify config file unchanged
+cat ~/.config/thoughtful/config.json | jq -r '.apiUrl'
+```

package/README.md

@@ -0,0 +1,300 @@
+# @tfl-inc/cli
+
+Command-line interface for interacting with your Thoughtful workspace.
+
+## Installation
+
+```bash
+npm install -g @tfl-inc/cli
+```
+
+Or with bun:
+
+```bash
+bun add -g @tfl-inc/cli
+```
+
+## 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.tokatsu.ai)
+
+```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.tokatsu.ai",
+  "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.tokatsu.ai`):
+  - 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.tokatsu.ai`
+
+## 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