sprid

The Sprid command line. Log in once, connect the stores and the channels, and see what needs you. Node 18+. Screenshot composition and releases also need Bun.

Sprid runs the marketing loop for an app: the agent does the work, the server remembers, watches and publishes, the person approves. Connected workflows share server records across REST, Sprid MCP and the dashboard. The CLI adds terminal access and local media production. Credentials stay out of conversations: CLI key-file commands and secure Sprid forms handle them.

Read sprid docs local for the complete local-to-chat handoff, or sprid docs chat for a browser-only workflow. sprid media builds and uploads; sprid post create, get, update, preview --id and deliveries operate on shared posts.

bunx @sprid/cli login            # or:  npm i -g @sprid/cli && sprid login

Local tools

Install once with npm install -g @sprid/cli. The support packages install with it:

sprid screenshots --config aso.config.ts
sprid release metadata --config release.config.ts  # dry run
sprid release metadata --execute                  # send reviewed changes
sprid post help

npm install -D @sprid/cli adds config helpers at @sprid/cli/screenshots (types) and @sprid/cli/release (defineReleaseConfig) to an app repo. The underlying @sprid/shots and @sprid/release remain importable libraries. Both subpaths are TypeScript source, so they are for Bun or a TypeScript build; Node cannot import them directly. The sprid-shots and sprid-release binaries run under Node and re-exec under Bun, so a missing Bun says so. The commands above need Bun for TypeScript configs. Configs are executable code; use trusted repos. --json wraps local-tool output with ok, exitCode, output and outputTruncated. Repo apiUrl settings must match the service selected by login or SPRID_URL; they cannot silently send your token to another host.

First connection

$ sprid login
  Open https://app.sprid.studio/device?code=FQRK-9M2P and enter  FQRK-9M2P
  (opening browser…)
  ✓ [email protected] · workspace example-team · Pulse

$ sprid init                      # or /sprid:bootstrap in the agent; same result
  ✓ Created App Profile myapp (My App) from .sprid/app.json
    appStoreId       6740000000
    playPackageName  com.example.myapp
  Still missing:
    – App Store Connect  →  sprid connect asc --app myapp --key ~/Downloads/AuthKey_XXXX.p8 --key-id XXXX --issuer YYYY
    – Google Play        →  sprid connect play --app myapp --key ~/Downloads/play-service-account.json

$ sprid connect
  Missing keys
    – Google Play · My App  →  sprid connect play --app myapp --key ~/Downloads/play-service-account.json
  Channels not connected
    – instagram @myapp     →  sprid connect instagram --account myapp
  Optional (no id on the profile yet)
    myapp: PostHog, RevenueCat, Search Console, Cloudflare

$ sprid connect instagram --account myapp
  Open https://www.facebook.com/…
  Opening the browser… waiting for Instagram
  ✓ @myapp_social connected to myapp

$ sprid status
  NEXT         1  Approve "you opened the app to write"   sprid open post 412
               2  Reply to a 2★ review from yesterday     sprid reviews reply 9
               3  Queue runs dry Thu 12 Sep               sprid open calendar
  CONNECTIONS  myapp   instagram ✓  tiktok ✗ (revoked)
               My App   asc ✓ 07:00  play ✓ 07:00
  QUEUE        2 scheduled · next Tue 09:00 @myapp_social · 0 failed
  APPS         myapp  asc ✓  play ✓  posthog –  revenuecat –  gsc –  cloudflare –
  PLAN         Pulse trial · 1/1 apps · 1/2 accounts · 1/4 channels

Connections are grouped one line per account (channels) and one per App Profile (sensors): ✓ ok, ~ expiring, ✗ revoked or the last pull failed, – key missing. The PLAN line ends with · BYOK anthropic ✓ or · BYOK – once the server reports the workspace's model key. When the token sees several workspaces, the first line names the one you are reading.

Every line of status is one field of the server's GET /api/status. The web Home card, the Monday mail and the plugin's closing message print the same list.

Investigate connected data

sprid marketing-review collects the review packet. Follow up through the same saved connections:

sprid docs queries --offline
sprid marketing-review capabilities --app myapp --source gsc --json
sprid marketing-review query --app myapp --source gsc --operation search --params-file search.json --json

The catalogue supplies the supported operations and JSON parameter schemas. The server pins resource IDs to the App Profile; provider keys stay on Sprid. Follow next.params, keep coverage/truncation with the results, and preserve provider units. Social reads use stored metrics and collected comments. Repository database reads remain local. See query documentation.

Commands and setup guides

sprid help and the public CLI reference read the same command catalog. sprid docs cli always describes the installed executable, even when the server is newer. Help works offline without login.

sprid help post create      # focus on one operation
sprid post create --help    # equivalent; never creates a draft
sprid help --json           # installed syntax and summaries for agents
sprid docs search posthog permissions
sprid docs                  # list guides and references
sprid docs posthog          # current setup steps, permissions and checks
sprid docs revenuecat --json
sprid docs posthog --offline # bundled copy, without a network request

Guides require no login. When the current guide cannot be fetched, output identifies the bundled fallback. JSON includes source and each connection guide’s revision. Search uses bundled content and shows ten matches by default; --limit N changes that. JSON search includes the full match count and a command to read each result.

Load completion in the current shell:

source <(sprid completion bash)       # Bash
source <(sprid completion zsh)        # Zsh, after compinit
sprid completion fish | source       # Fish

These commands print a script and do not edit your shell configuration. Completion suggests catalog commands, subcommands, documented flags and guide names. Dynamic account names and IDs still come from sprid apps and connected reads. Save the script in your shell's completion directory to retain it; regenerate after updating.

Always pass a key file when connecting through an agent. A successful sensor connect means the key was saved: JSON returns verified: false and a verifyCommand. Run that command without --check; inspect the individual source’s data and errors.

--app is optional when there is one App Profile or .sprid/app.json identifies it.

Which workspace

Workspace selection: explicit --workspace, the app profile's workspaceId, saved login choice, sole available workspace, then the app profile's workspace slug. Use sprid use <slug> to save a choice; it also works with an environment token.

Credentials

sprid login writes ~/.sprid/credentials.json (mode 0600, directory 0700):

{ "apiUrl": "https://api.sprid.studio", "token": "sprd_…", "tokenId": 7,
  "workspace": { "id": 1, "slug": "example-team", "name": "Example Team", "tier": "starter" },
  "email": "[email protected]" }

The token is an ordinary personal access token named sprid <version> on <hostname>, pinned to the workspace you picked in the browser. Revoke it with sprid logout or in Settings → Tokens.

Resolution order, every command: SPRID_PAT in the environment wins; otherwise the file; otherwise a clear "run sprid login". SPRID_URL overrides the API base (http://localhost:4005 for a dev server). SPRID_APP_URL overrides the web app URL, which is otherwise derived by turning api. into app..

--json for agents

Commands take --json and write one JSON document to stdout, including on failure ({"ok":false,"error":"…","status":401}), with the exit code preserved. Things a person needs to act on during a run (the login code, the OAuth URL) go to stderr so stdout stays parseable. sprid connect asc --json reports which secret keys are now set, never their values. Unknown commands and missing flag values also return JSON. The mcp command is a streaming protocol transport and is exempt. Local screenshot and release tools return an envelope with ok, exitCode and captured output; local media can include per-post check failures.

Exit codes: 0 success, 1 runtime/auth/API failure, 2 usage or an explicit choice needed. Local tools can propagate other nonzero codes. Use sprid help exit-codes and sprid help environment for the scripting contract and configuration precedence. Read saved state before retrying a failed mutation: a network error does not prove that the server did nothing.

sprid status --json | jq '.next[0].cli'

Using sprid mcp

Most MCP clients can talk to https://api.sprid.studio/api/mcp over HTTP directly. For one that only speaks stdio:

claude mcp add sprid -- sprid mcp

It uses the sprid login credentials (or SPRID_PAT). --surface all lists the full catalog instead of the ~25 core verbs.

What it touches

Reads: the key files you name on the command line, .sprid/app.json in the current directory, ~/.sprid/secrets/<slug>.json with --from-local, ~/.sprid/credentials.json.

Writes: ~/.sprid/credentials.json on login, .sprid/app.json when sprid init is run with flags. Setup and connection commands also save local progress. sprid post writes the media registry, captions and previews; sprid screenshots writes store images; sprid release writes configured build artifacts and logs. Update checks cache registry metadata in ~/.sprid/updates/; explicit updates replace installed packages and, for project installations, update dependency declarations and locks.

Sends: key file contents go to your App Profile over TLS with your token, in the request body of PATCH /api/app-profiles/:id. They are stored encrypted and no route ever returns them. sprid connect <platform> only opens the platform’s OAuth page and waits for the result. Publishing requires the relevant approval or publishing command.

Usage telemetry: when you are signed in, each command ends with one request to POST /api/cli/events on the API you are signed in to, carrying the command name, a documented subcommand (post push, never a slug or a file name), the exit code, an error kind (an HTTP status, or usage/network/other, never the message), the duration, the CLI and Node versions, the OS and whether CI is set. Never arguments, paths, output or file contents, and nothing goes to any third party. The first run that could send only prints a notice. It waits at most one second and a failure is ignored. Turn it off with sprid telemetry off (saved in ~/.sprid/telemetry.json), or for one shell with DO_NOT_TRACK=1 or SPRID_TELEMETRY=0; help, version, completion and mcp never send.

Install ping: once a day per surface, signed in or not, one anonymous request to POST /api/installs/ping carrying a random id created in ~/.sprid/telemetry.json, the surface (cli, or claude, codex or skills when sprid doctor --plugin reports how the skills were installed), the CLI and skills versions, the OS and Node versions, whether CI is set and whether a login exists. No token, account or workspace. It is how an install that never signs in is counted. Same notice, same switches.

Credentials stay out of normal output. Build tools can print their own logs; do not include secrets in custom build commands.

Updates

sprid doctor --json reports the running version, npm's recommended latest version, compatibility and the detected installation. Checks are cached for one day; --offline reads cache only. Registry failures do not block ordinary work. status and next also report available updates on stderr, keeping stdout JSON unchanged.

Use sprid update --check to inspect and sprid update to install. It updates the running installation, pins the selected version, and verifies a new CLI process. Global npm installs keep their npm prefix; project dependencies use the detected npm, pnpm, Bun or Yarn manager and preserve dev/optional dependency placement. Project updates change package.json and the lockfile. Lifecycle builds are skipped; package-manager configuration is still trusted code. Source checkouts, linked or ambiguous installations and Windows self-updates are refused with instructions. Use the original package manager manually for those installations.

Automatic installation is off by default. sprid update --auto on opts in for this installation; --auto off disables it. Settings and cache live in ~/.sprid/updates/. At a job boundary, sprid doctor --apply-updates --json installs a verified compatible update if opted in. Ordinary commands never install updates. Start a new process after updated: true; do not retry completed publishing operations.

Major releases, minor releases before 1.0, and all 0.0.x changes require explicit sprid update --yes. Automatic updates never cross those boundaries. A failed installation may have changed files: inspect the installation/lockfile before retrying. The plugin updates separately through the agent client's plugin manager.

© 2026 Väder AB. All rights reserved. Use is subject to Sprid's Terms of Service.