circleinbox 0.1.0

package/README.md

@@ -0,0 +1,210 @@
+# CircleInbox CLI
+
+Email infrastructure for agents and developers. Manage inboxes, send email, store credentials, and orchestrate password resets — all from the command line.
+
+## Installation
+
+```bash
+npm install -g @circleinbox/cli
+```
+
+Or run directly:
+
+```bash
+npx @circleinbox/cli help
+```
+
+## Quick Start
+
+```bash
+# 1. Login with your API key
+circleinbox login --key ci_live_YOUR_KEY
+
+# 2. Check connection
+circleinbox status
+
+# 3. List your domains
+circleinbox domains list
+
+# 4. Check inbox
+circleinbox inbox check hello@example.com
+
+# 5. Send an email
+circleinbox send --from hello@example.com --to user@gmail.com --subject "Hello" --text "Hi there!"
+```
+
+## Authentication
+
+API keys are encrypted with AES-256-GCM and stored at `~/.circleinbox/credentials`. On macOS, the encryption key is stored in the system keychain.
+
+```bash
+circleinbox login                     # Interactive prompt
+circleinbox login --key ci_live_...   # Direct key
+CIRCLEINBOX_API_KEY=ci_live_... circleinbox status  # Env var fallback
+circleinbox logout                    # Remove credentials
+```
+
+## Commands
+
+### General
+
+| Command | Description |
+|---------|-------------|
+| `login [--key <key>]` | Store API key (encrypted) |
+| `logout` | Remove stored credentials |
+| `status` | Show connection status and org info |
+| `version` | Show CLI version |
+| `help` | Show all commands |
+
+### Domains
+
+```bash
+circleinbox domains list              # List all domains with DNS status
+circleinbox dns check example.com     # Check DNS records for a domain
+```
+
+DNS check shows MX, SPF, DKIM, and DMARC status with required records for any missing entries.
+
+### Inboxes
+
+```bash
+circleinbox inbox list                          # List all mailboxes
+circleinbox inbox create hello@example.com      # Create a new mailbox
+circleinbox inbox check hello@example.com       # List emails (default: 20)
+circleinbox inbox check hello@example.com -l 50 # List 50 emails
+circleinbox inbox read hello@example.com 1      # Read email UID 1
+circleinbox inbox delete hello@example.com      # Delete mailbox (with confirmation)
+```
+
+Mailbox arguments accept either an email address or a mailbox UUID.
+
+### Send Email
+
+```bash
+# Basic send
+circleinbox send --from hello@example.com --to user@gmail.com \
+  --subject "Hello" --text "Message body"
+
+# With HTML
+circleinbox send --from hello@example.com --to user@gmail.com \
+  --subject "Hello" --html "<p>Message body</p>"
+
+# With idempotency key (prevents duplicate sends)
+circleinbox send --from hello@example.com --to user@gmail.com \
+  --subject "Hello" --text "Body" --idempotency-key unique-123
+
+# Pipe body from stdin
+echo "Hello from pipe" | circleinbox send --from hello@example.com \
+  --to user@gmail.com --subject "Piped" --text -
+```
+
+### Aliases
+
+```bash
+circleinbox alias list                                    # List all aliases
+circleinbox alias list --domain example.com               # Filter by domain
+circleinbox alias create support@example.com hello@example.com  # Create alias
+circleinbox alias update ALIAS_ID newemail@example.com    # Update destinations
+circleinbox alias delete ALIAS_ID                         # Delete alias
+```
+
+### Vault (Credentials)
+
+Store and retrieve website login credentials, encrypted in MechVault.
+
+```bash
+# List credentials for a mailbox (no passwords shown)
+circleinbox vault list hello@example.com
+
+# Store a credential (password auto-generated if not provided)
+circleinbox vault store hello@example.com \
+  --service https://github.com \
+  --username hello@example.com \
+  --notes "2FA enabled"
+
+# Get credential with password
+circleinbox vault get hello@example.com a1b2c3d4e5f6
+
+# Update credential
+circleinbox vault update hello@example.com a1b2c3d4e5f6 \
+  --password "new-password" \
+  --notes "Updated 2026-02-13"
+
+# Delete credential
+circleinbox vault delete hello@example.com a1b2c3d4e5f6
+```
+
+### Password Reset
+
+Orchestrated password reset flow that polls for reset emails and extracts reset links.
+
+```bash
+# Generic flow (for any website)
+# 1. Looks up credential  2. You trigger reset in browser
+# 3. Polls inbox for email  4. Extracts reset links  5. Updates vault
+circleinbox reset hello@example.com a1b2c3d4e5f6
+
+# ClearAuth direct API flow (no browser needed)
+circleinbox reset hello@example.com a1b2c3d4e5f6 --clearauth
+
+# With pre-set new password
+circleinbox reset hello@example.com a1b2c3d4e5f6 --password "new-pass"
+```
+
+### Provision
+
+Full domain-to-mailbox provisioning in one command.
+
+```bash
+# Provision with defaults (hello@domain.com)
+circleinbox provision example.com
+
+# Custom local part and display name
+circleinbox provision example.com --local support --display "Support"
+
+# Dry run (show what would happen)
+circleinbox provision example.com --dry-run
+```
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output raw JSON (for piping to `jq`) |
+| `--quiet` | Suppress decorative output |
+| `--api-url <url>` | Override API base URL |
+
+### JSON output examples
+
+```bash
+# Pipe to jq for structured queries
+circleinbox domains list --json | jq '.data[] | {domain, status}'
+circleinbox inbox check hello@example.com --json | jq '.data.emails[] | {uid, subject}'
+circleinbox vault get hello@example.com hash --json | jq '.data.password'
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CIRCLEINBOX_API_KEY` | API key fallback (if not logged in) |
+
+## Configuration
+
+Config stored at `~/.circleinbox/config.json`:
+
+```json
+{
+  "apiUrl": "https://circleinbox.com/api/v1",
+  "outputFormat": "pretty"
+}
+```
+
+## Requirements
+
+- Node.js 20+
+- CircleInbox API key (`ci_live_` prefix)
+
+## License
+
+MIT