The Sophic CLI
sophic-support-kbSophicUpdated Jun 5, 2026
# 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.