diff --git a/README.md b/README.md index 253eb69..51a406f 100644 --- a/README.md +++ b/README.md @@ -32,26 +32,29 @@ shelltime daemon install # Optional: background sync for <8ms latency ## Configuration -Config file: `~/.shelltime/config.toml` +Config file: `~/.shelltime/config.yaml` -```toml -token = "your-token" -flushCount = 10 # Commands before sync -gcTime = 14 # Days to retain data -dataMasking = true # Mask sensitive data -encrypted = false # E2E encryption (requires daemon) +```yaml +token: "your-token" +flushCount: 10 # Commands before sync +gcTime: 14 # Days to retain data +dataMasking: true # Mask sensitive data +encrypted: false # E2E encryption (requires daemon) # Exclude patterns (regex) -exclude = [".*password.*", "^export .*"] +exclude: + - ".*password.*" + - "^export .*" # AI permissions -[ai.agent] -view = false # Read-only commands -edit = false # File modifications -delete = false # Destructive commands +ai: + agent: + view: false # Read-only commands + edit: false # File modifications + delete: false # Destructive commands ``` -Local overrides: `~/.shelltime/config.local.toml` +Local overrides: `~/.shelltime/config.local.yaml` **[Full Configuration Guide](docs/CONFIG.md)** - Detailed documentation for all options diff --git a/docs/CONFIG.md b/docs/CONFIG.md index bf0b17d..fa7d3f7 100644 --- a/docs/CONFIG.md +++ b/docs/CONFIG.md @@ -19,11 +19,11 @@ This guide explains all configuration options available in ShellTime CLI. Config ## Quick Start -Create a configuration file at `~/.shelltime/config.toml`: +Create a configuration file at `~/.shelltime/config.yaml`: -```toml +```yaml # Minimal configuration - just your API token -token = "your-api-token-from-shelltime.xyz" +token: "your-api-token-from-shelltime.xyz" ``` That's it! ShellTime works with sensible defaults. Read on to customize your experience. @@ -36,31 +36,33 @@ ShellTime uses two configuration files: | File | Location | Purpose | |------|----------|---------| -| `config.toml` | `~/.shelltime/config.toml` | Main configuration | -| `config.local.toml` | `~/.shelltime/config.local.toml` | Local overrides (for sensitive data) | +| `config.yaml` | `~/.shelltime/config.yaml` | Main configuration | +| `config.local.yaml` | `~/.shelltime/config.local.yaml` | Local overrides (for sensitive data) | + +> **Note:** TOML format (`config.toml`, `config.local.toml`) is also supported. YAML files take priority when both exist. ### How Merging Works Local config values **override** base config values. This lets you: -- Keep `config.toml` in version control (without secrets) -- Store tokens and sensitive settings in `config.local.toml` (add to `.gitignore`) +- Keep `config.yaml` in version control (without secrets) +- Store tokens and sensitive settings in `config.local.yaml` (add to `.gitignore`) **Example:** -```toml -# config.toml -token = "" -flushCount = 5 -dataMasking = true +```yaml +# config.yaml +token: "" +flushCount: 5 +dataMasking: true -# config.local.toml -token = "my-secret-token" -flushCount = 10 +# config.local.yaml +token: "my-secret-token" +flushCount: 10 # Result after merge: -# token = "my-secret-token" (from local) -# flushCount = 10 (from local) -# dataMasking = true (from base) +# token: "my-secret-token" (from local) +# flushCount: 10 (from local) +# dataMasking: true (from base) ``` --- @@ -75,15 +77,15 @@ flushCount = 10 | `apiEndpoint` | string | No | `https://api.shelltime.xyz` | | `webEndpoint` | string | No | `https://shelltime.xyz` | -```toml +```yaml # Your API token from shelltime.xyz -token = "your-api-token" +token: "your-api-token" # Custom API endpoint (for self-hosted instances) -apiEndpoint = "https://api.shelltime.xyz" +apiEndpoint: "https://api.shelltime.xyz" # Web dashboard URL -webEndpoint = "https://shelltime.xyz" +webEndpoint: "https://shelltime.xyz" ``` ### Sync Settings @@ -93,12 +95,12 @@ webEndpoint = "https://shelltime.xyz" | `flushCount` | integer | `10` | Commands buffered before syncing | | `gcTime` | integer | `14` | Days to retain data on server | -```toml +```yaml # Sync after every 10 commands (minimum: 3) -flushCount = 10 +flushCount: 10 # Keep 2 weeks of history on server -gcTime = 14 +gcTime: 14 ``` **How syncing works:** @@ -113,9 +115,9 @@ gcTime = 14 |--------|------|---------| | `socketPath` | string | `/tmp/shelltime.sock` | -```toml +```yaml # Custom socket path for CLI-daemon communication -socketPath = "/tmp/shelltime.sock" +socketPath: "/tmp/shelltime.sock" ``` --- @@ -130,9 +132,9 @@ socketPath = "/tmp/shelltime.sock" Data masking automatically redacts sensitive information before syncing: -```toml +```yaml # Enable automatic masking of sensitive data (recommended) -dataMasking = true +dataMasking: true ``` **What gets masked:** @@ -157,9 +159,9 @@ export AWS_SECRET_ACCESS_KEY=***MASKED*** |--------|------|---------|--------------| | `encrypted` | boolean | `false` | Daemon mode + token capability | -```toml +```yaml # Enable E2E encryption (requires daemon mode) -encrypted = true +encrypted: true ``` **Important:** @@ -179,16 +181,15 @@ encrypted = true Filter out commands you don't want tracked using regex patterns: -```toml -exclude = [ - ".*password.*", # Commands containing "password" - "^export AWS_", # AWS credential exports - "^ssh.*root", # SSH to root - "^gpg.*--decrypt", # GPG decryption - "^history", # History commands - "(?i)secret", # Case-insensitive "secret" - "^mysql.*-p", # MySQL with password flag -] +```yaml +exclude: + - ".*password.*" # Commands containing "password" + - "^export AWS_" # AWS credential exports + - "^ssh.*root" # SSH to root + - "^gpg.*--decrypt" # GPG decryption + - "^history" # History commands + - "(?i)secret" # Case-insensitive "secret" + - "^mysql.*-p" # MySQL with password flag ``` **Pattern syntax:** Uses Go's standard regex syntax (not PCRE). [Reference](https://pkg.go.dev/regexp/syntax) @@ -207,20 +208,20 @@ ShellTime includes AI-powered command suggestions via `shelltime q`. ### AI Configuration -```toml -[ai] -# Show helpful tips when using AI features -showTips = true +```yaml +ai: + # Show helpful tips when using AI features + showTips: true -[ai.agent] -# Auto-execute read-only commands (ls, cat, etc.) -view = false + agent: + # Auto-execute read-only commands (ls, cat, etc.) + view: false -# Auto-execute file modification commands -edit = false + # Auto-execute file modification commands + edit: false -# Auto-execute delete commands (DANGEROUS - not recommended) -delete = false + # Auto-execute delete commands (DANGEROUS - not recommended) + delete: false ``` ### Auto-Execution Levels @@ -232,11 +233,12 @@ delete = false | Delete | `ai.agent.delete` | `rm`, `rmdir` | High | **Recommended settings:** -```toml -[ai.agent] -view = true # Safe - only reads -edit = false # Requires confirmation -delete = false # Always requires confirmation +```yaml +ai: + agent: + view: true # Safe - only reads + edit: false # Requires confirmation + delete: false # Always requires confirmation ``` --- @@ -255,11 +257,11 @@ The modern approach using OpenTelemetry gRPC passthrough: | `ccotel.grpcPort` | integer | `54027` | gRPC server port | | `ccotel.debug` | boolean | `false` | Write debug files | -```toml -[ccotel] -enabled = true -grpcPort = 54027 # Default ShellTime OTEL port -debug = false # Set true to debug issues +```yaml +ccotel: + enabled: true + grpcPort: 54027 # Default ShellTime OTEL port + debug: false # Set true to debug issues ``` **How it works:** @@ -271,25 +273,31 @@ debug = false # Set true to debug issues CLI-based collection (older method): -```toml -[ccusage] -enabled = false +```yaml +ccusage: + enabled: false ``` ### Code Tracking Track coding activity heartbeats: -```toml -[codeTracking] -enabled = false -# Optional: use a custom API endpoint for heartbeats (defaults to global apiEndpoint) -apiEndpoint = "https://api.custom-heartbeat.com" -# Optional: use a custom token for heartbeats (defaults to global token) -token = "custom-heartbeat-token" +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `codeTracking.enabled` | boolean | `false` | Enable heartbeat tracking | +| `codeTracking.apiEndpoint` | string | - | Custom API endpoint for heartbeats | +| `codeTracking.token` | string | - | Custom token for heartbeats | + +```yaml +codeTracking: + enabled: true + # Optional: use a custom API endpoint for heartbeats (defaults to global apiEndpoint) + apiEndpoint: "https://api.custom-heartbeat.com" + # Optional: use a custom token for heartbeats (defaults to global token) + token: "custom-heartbeat-token" ``` -When `apiEndpoint` or `token` is set under `[codeTracking]`, heartbeat data will use these values instead of the global configuration. This allows you to send coding activity to a different server or authenticate with a separate token. +When `apiEndpoint` or `token` is set under `codeTracking`, heartbeat data will use these values instead of the global configuration. This allows you to send coding activity to a different server or authenticate with a separate token. --- @@ -299,19 +307,18 @@ When `apiEndpoint` or `token` is set under `[codeTracking]`, heartbeat data will Sync to multiple servers simultaneously: -```toml +```yaml # Primary endpoint -token = "primary-token" -apiEndpoint = "https://api.shelltime.xyz" +token: "primary-token" +apiEndpoint: "https://api.shelltime.xyz" # Additional endpoints (synced in parallel) -[[endpoints]] -apiEndpoint = "https://backup-api.example.com" -token = "backup-token" +endpoints: + - apiEndpoint: "https://backup-api.example.com" + token: "backup-token" -[[endpoints]] -apiEndpoint = "https://enterprise.internal.com" -token = "enterprise-token" + - apiEndpoint: "https://enterprise.internal.com" + token: "enterprise-token" ``` ### Log Cleanup @@ -323,10 +330,10 @@ Automatic cleanup of log files: | `logCleanup.enabled` | boolean | `true` | Enable auto-cleanup | | `logCleanup.thresholdMB` | integer | `100` | File size limit in MB | -```toml -[logCleanup] -enabled = true -thresholdMB = 100 # Clean files larger than 100MB +```yaml +logCleanup: + enabled: true + thresholdMB: 100 # Clean files larger than 100MB ``` **Files cleaned:** @@ -344,9 +351,9 @@ Cleanup runs every 24 hours when daemon is active. |--------|------|---------| | `enableMetrics` | boolean | `false` | -```toml +```yaml # Enable OTEL metrics (has performance impact) -enableMetrics = false +enableMetrics: false ``` **Warning:** Enabling metrics adds overhead to every command. Only use for debugging. @@ -357,70 +364,68 @@ enableMetrics = false Here's a full configuration with all options: -```toml +```yaml # ============================================ # ShellTime CLI Configuration # ============================================ # --- Authentication --- -token = "your-api-token" -apiEndpoint = "https://api.shelltime.xyz" -webEndpoint = "https://shelltime.xyz" +token: "your-api-token" +apiEndpoint: "https://api.shelltime.xyz" +webEndpoint: "https://shelltime.xyz" # --- Sync Settings --- -flushCount = 10 # Sync every 10 commands -gcTime = 14 # Keep 14 days of history +flushCount: 10 # Sync every 10 commands +gcTime: 14 # Keep 14 days of history # --- Privacy --- -dataMasking = true # Mask sensitive data -encrypted = false # E2E encryption (requires daemon) +dataMasking: true # Mask sensitive data +encrypted: false # E2E encryption (requires daemon) # --- Command Filtering --- -exclude = [ - ".*password.*", - "^export AWS_", - "^export.*SECRET", - "^ssh.*root", - "^gpg.*--decrypt", - "^history", -] +exclude: + - ".*password.*" + - "^export AWS_" + - "^export.*SECRET" + - "^ssh.*root" + - "^gpg.*--decrypt" + - "^history" # --- AI Configuration --- -[ai] -showTips = true - -[ai.agent] -view = true -edit = false -delete = false +ai: + showTips: true + agent: + view: true + edit: false + delete: false # --- Claude Code Integration --- -[ccotel] -enabled = false -grpcPort = 54027 -debug = false +ccotel: + enabled: false + grpcPort: 54027 + debug: false -[ccusage] -enabled = false +ccusage: + enabled: false -[codeTracking] -enabled = false -# apiEndpoint = "https://api.custom-heartbeat.com" # Optional: custom endpoint -# token = "custom-heartbeat-token" # Optional: custom token +codeTracking: + enabled: false + # apiEndpoint: "https://api.custom-heartbeat.com" # Optional: custom endpoint + # token: "custom-heartbeat-token" # Optional: custom token # --- Log Management --- -[logCleanup] -enabled = true -thresholdMB = 100 +logCleanup: + enabled: true + thresholdMB: 100 # --- Advanced --- -socketPath = "/tmp/shelltime.sock" -enableMetrics = false +socketPath: "/tmp/shelltime.sock" +enableMetrics: false # --- Additional Sync Targets --- -# [[endpoints]] -# apiEndpoint = "https://backup.example.com" -# token = "backup-token" +# endpoints: +# - apiEndpoint: "https://backup.example.com" +# token: "backup-token" ``` --- @@ -432,8 +437,8 @@ enableMetrics = false All ShellTime data lives in `~/.shelltime/`: ``` ~/.shelltime/ -├── config.toml # Main configuration -├── config.local.toml # Local overrides (add to .gitignore) +├── config.yaml # Main configuration +├── config.local.yaml # Local overrides (add to .gitignore) ├── log.log # CLI logs ├── sync-pending.txt # Pending sync data └── logs/ # Daemon logs (macOS) @@ -447,20 +452,21 @@ shelltime doctor ### Why isn't my local config being applied? -1. Ensure file is named exactly `config.local.toml` -2. Check TOML syntax (use a TOML validator) +1. Ensure file is named exactly `config.local.yaml` (or `config.local.toml`) +2. Check YAML syntax (use a YAML validator) 3. Only non-empty values override base config ### How do I disable tracking temporarily? Add a catch-all exclude pattern: -```toml -exclude = [".*"] +```yaml +exclude: + - ".*" ``` Or unset your token: -```toml -token = "" +```yaml +token: "" ``` ### What's the difference between CCOtel and CCUsage?