The Sophic CLI

# The Sophic CLI The `sophic` CLI lets you capture notes and bulk-import files into your Sophic knowledge base straight from your terminal. This guide covers installation, login, the core commands, and environment overrides. ## Install The CLI is published to npm and runs on Node.js. The binary is `sophic`. ```bash npm install -g sophic ``` ## Log in `sophic login` opens your browser for single sign-on, then stores a Personal Access Token (PAT) and your workspace list locally. ```bash sophic login ``` Credentials are written to `~/.sophic/config.json` with `0600` file permissions (readable only by you). On the server, PATs are stored only as SHA-256 hashes and can be revoked or set to expire. ## Capture a note Pass quoted text to ingest a note into your active workspace. If you omit the text, the CLI reads from stdin, so you can pipe content in. ```bash # Inline text sophic capture "Staging deploys need the VPN; the runner can't reach the DB otherwise." # From stdin git log -1 --format=%B | sophic capture ``` Captures are idempotent — the CLI sends an idempotency key, so retries won't create duplicates. Note that very short captures are rejected; there's a minimum word count. ## Bulk import Import a directory of text files (such as `.md` and `.txt`) in one pass. ```bash sophic import ./docs ``` Imported content lands in the capture buffer, where a background sweep consolidates it into documents with dedup, cleanup, and topic tagging. ## Workspace commands Each workspace isolates its own data, so make sure you're pointed at the right one. ```bash sophic workspace list # show workspaces you belong to sophic workspace use # set the active workspace sophic workspace show # show the active workspace ``` ## Environment overrides You can override config for scripting or CI without running `sophic login`: | Variable | Purpose | Default | | --- | --- | --- | | `SOPHIC_PAT` | Personal Access Token to authenticate with | — | | `SOPHIC_API_URL` | Sophic API base URL | `https://app.sophic.so` | | `SOPHIC_WORKSPACE` | Workspace slug to target | — | ```bash SOPHIC_PAT="$SOPHIC_PAT" \ SOPHIC_WORKSPACE=acme-eng \ sophic capture "Release 2.4 shipped; rollback steps are in the on-call doc." ``` ## Troubleshooting **My capture was rejected.** Captures below the minimum word count are rejected. Add a sentence or two of context and try again. **The CLI says I'm not authenticated.** Run `sophic login` again, or set `SOPHIC_PAT` in your environment. Tokens can be revoked or expire, so a previously valid token may need to be reissued. **My note went to the wrong workspace.** Check `sophic workspace show`, then switch with `sophic workspace use ` or set `SOPHIC_WORKSPACE` for the current command. **I re-ran a capture — did it duplicate?** No. CLI captures are idempotent, so safe retries won't create duplicate entries.