Skip to main content

CLI Reference

The Sophic CLI (usesophic) lets you authenticate, capture knowledge, and manage workspaces from your terminal.

Installation​

npm install -g usesophic

This installs the sophic command globally.

Commands​

sophic login​

Authenticate via browser SSO and select your active workspace.

sophic login

Opens your browser to complete authentication. On success, a Personal Access Token and workspace list are saved to ~/.sophic/config.json. If you belong to multiple workspaces, you'll be prompted to choose one interactively.

Options:

FlagDefaultDescription
--url <url>https://app.sophichq.coSophic server URL

Alias: sophic setup

sophic capture​

Send a text snippet to the Sophic ingestion pipeline.

sophic capture "Redis failover: switch to replica-2, then promote via redis-cli"

You can also pipe content from stdin:

echo "Deploy note: always run migrations first" | sophic capture
pbpaste | sophic capture
cat incident-notes.txt | sophic capture

Pass - explicitly to read from stdin:

sophic capture -

Arguments:

ArgumentRequiredDescription
textNoThe text to capture. Omit or pass - to read from stdin.

Exit codes:

CodeMeaning
0Captured successfully
1Authentication error, empty text, network error, or server error

sophic workspace list​

Show all cached workspaces. The active workspace is marked with *.

sophic workspace list
  * acme-eng       Acme Engineering  owner
    acme-platform  Acme Platform     editor

sophic workspace use <slug>​

Switch the active workspace by slug. The slug must match a workspace in your cached list — if it doesn't, the command prints available options.

sophic workspace use acme-platform

sophic workspace show​

Display the currently active workspace.

sophic workspace show
  Workspace: Acme Engineering
  Slug:      acme-eng
  Role:      owner

Configuration​

The CLI stores credentials and workspace state in ~/.sophic/config.json:

{
  "personalToken": "...",
  "apiUrl": "https://app.sophichq.co",
  "activeWorkspace": "acme-eng",
  "workspaces": [
    { "slug": "acme-eng", "name": "Acme Engineering", "role": "owner" }
  ]
}

Environment variables​

Override config file values with environment variables — useful for CI/CD:

VariableDescription
SOPHIC_PATPersonal Access Token (overrides personalToken in config)
SOPHIC_API_KEYAlias for SOPHIC_PAT (backwards compatibility)
SOPHIC_API_URLAPI base URL (overrides apiUrl in config)
SOPHIC_WORKSPACEWorkspace slug (overrides activeWorkspace in config)

Next steps​