@sprid/cli 0.1.2

package/README.md

@@ -0,0 +1,249 @@
+# 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:
+
+```sh
+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…)
+  ✓ user@example.com · 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:
+
+```sh
+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](https://sprid.studio/docs/queries).
+
+## Commands and setup guides
+
+`sprid help` and the [public CLI reference](https://sprid.studio/docs/cli) read the
+same command catalog. `sprid docs cli` always describes the installed executable,
+even when the server is newer. Help works offline without login.
+
+```sh
+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:
+
+```sh
+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`):
+
+```json
+{ "apiUrl": "https://api.sprid.studio", "token": "sprd_…", "tokenId": 7,
+  "workspace": { "id": 1, "slug": "example-team", "name": "Example Team", "tier": "starter" },
+  "email": "you@example.com" }
+```
+
+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.
+
+No background telemetry. 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](https://sprid.studio/terms).

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security
+
+Email hello@sprid.studio with `security` in the subject. Please do not open a
+public issue for anything exploitable. Say what you did, what happened, and
+the version (`sprid --version`). We reply within three working days. No bug
+bounty.
+
+**In scope:** anything that exposes a credential this tool holds or reads (the
+token in `~/.sprid/credentials.json`, a store or provider key named by a
+config) in output, a log, an error or a request to somewhere it does not
+belong. Also a path that lets a server response write outside its directory,
+run code, or widen what a token may do.
+
+**Not a bug:** a config file is executable code. `release.config.ts`,
+`aso.config.ts` and a post spec are run by the tool that reads them, so an
+untrusted repository runs its author's code. Use trusted repositories.
+
+Only the latest published version is patched.

package/bin.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { run } from "./src/cli.mjs";
+
+run(process.argv.slice(2), { notifyUpdates: true }).then(
+  // Let stdout drain. An explicit exit truncates large review packets when
+  // another process is reading the CLI through a pipe.
+  (code) => { process.exitCode = code ?? 0; },
+  (e) => {
+    process.stderr.write(`\n  ✗ ${e && e.message ? e.message : e}\n\n`);
+    process.exitCode = 1;
+  },
+);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@sprid/cli",
+  "version": "0.1.2",
+  "description": "The Sprid command line: connect your app, review results, prepare posts and store screenshots, and release mobile apps.",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "homepage": "https://sprid.studio",
+  "bugs": {
+    "email": "hello@sprid.studio"
+  },
+  "keywords": [
+    "sprid",
+    "cli",
+    "mcp",
+    "app-store",
+    "marketing",
+    "instagram",
+    "tiktok"
+  ],
+  "bin": {
+    "sprid": "./bin.mjs"
+  },
+  "exports": {
+    "./screenshots": "./src/screenshots.ts",
+    "./release": "./src/release.ts"
+  },
+  "files": [
+    "bin.mjs",
+    "src",
+    "!src/**/__tests__/**",
+    "README.md",
+    "README-post.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@sprid/shots": "0.1.1",
+    "@sprid/release": "0.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/args.mjs

@@ -0,0 +1,134 @@
+// Argument parsing. One rule that has already been wrong elsewhere: a flag's
+// value is not a positional argument, so every flag that takes a value is
+// named here and skipped when collecting positionals.
+
+export const VALUE_FLAGS = new Set([
+  'revision', 'search', 'directory',
+  'history-before', 'history-before-id', 'history-limit',
+  'before', 'before-id',
+  'id', 'request-id',
+  "api",
+  "auto",
+  "file",
+  "task",
+  "payload",
+  "platform",
+  "entry",
+  "account",
+  "page",
+  "app",
+  "key",
+  "key-id",
+  "issuer",
+  "property",
+  "project",
+  "host",
+  "token",
+  "zone",
+  "role",
+  "surface",
+  "limit",
+  "days",
+  "query-file",
+  "view",
+  "sources",
+  "enabled",
+  "source",
+  "operation",
+  "params-file",
+  "since",
+  "end",
+  "workspace",
+  "max-rating",
+  "text",
+  // init
+  "name",
+  "slug",
+  "app-store-id",
+  "play-package",
+  "gsc-property",
+  "posthog-project",
+  "posthog-host",
+  "revenuecat-project",
+  "cloudflare-zone",
+  "repo-url",
+  "website-url",
+  "channel",
+  "board",
+  "section",
+  "title",
+  "description",
+  "link",
+  "alt-text",
+  "ai-disclosures",
+  "bookmark",
+]);
+
+export const BOOL_FLAGS = new Set(["json", "offline", "check", "no-browser", "from-local", "help", "version", "unanswered", "yes", "clear", "refresh", "cached-only"]);
+
+/**
+ * `sprid connect asc --app myapp --key ./k.p8 --json`
+ *   → { command: "connect", positionals: ["asc"], flags: { app: "myapp", key: "./k.p8", json: true } }
+ *
+ * Accepts `--flag value` and `--flag=value`. Unknown `--flags` are kept as
+ * booleans so a command can refuse them by name.
+ */
+export function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  let commandIndex = -1;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") {
+      if (commandIndex < 0 && argv[i + 1]) commandIndex = i + 1;
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq > 0) {
+        flags[a.slice(2, eq)] = a.slice(eq + 1);
+        continue;
+      }
+      const name = a.slice(2);
+      if (VALUE_FLAGS.has(name)) {
+        const v = argv[i + 1];
+        if (v === undefined || v.startsWith("--")) {
+          throw new UsageError(`--${name} needs a value`);
+        }
+        flags[name] = v;
+        i++;
+      } else {
+        flags[name] = true;
+      }
+      continue;
+    }
+    if (a === "-w") {
+      const v = argv[i + 1];
+      if (v === undefined || v.startsWith("-")) throw new UsageError("-w needs a workspace slug or id");
+      flags.workspace = v;
+      i++;
+      continue;
+    }
+    if (a === "-h") {
+      flags.help = true;
+      continue;
+    }
+    if (a === "-v") {
+      flags.version = true;
+      continue;
+    }
+    if (commandIndex < 0) commandIndex = i;
+    positionals.push(a);
+  }
+  const [command, ...rest] = positionals;
+  return { command, positionals: rest, flags, commandArgv: argv.slice(commandIndex + 1) };
+}
+
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+    this.exitCode = 2;
+  }
+}

package/src/browser.mjs

@@ -0,0 +1,28 @@
+// Open a URL in the person's browser, and never fail because of it: over SSH
+// or in a container there is no browser, and the URL is printed anyway.
+
+import { spawn } from "node:child_process";
+
+export async function openBrowser(url) {
+  let parsed;
+  try { parsed = new URL(url); } catch { return false; }
+  if (!['https:', 'http:'].includes(parsed.protocol) || parsed.username || parsed.password) return false;
+  const [cmd, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ['powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', 'Start-Process -FilePath $env:SPRID_OPEN_URL']]
+        : ["xdg-open", [url]];
+  return new Promise((resolve) => {
+    try {
+      const child = spawn(cmd, args, { stdio: "ignore", detached: true, env: { ...process.env, SPRID_OPEN_URL: parsed.href } });
+      child.on("error", () => resolve(false));
+      child.on("spawn", () => {
+        child.unref();
+        resolve(true);
+      });
+    } catch {
+      resolve(false);
+    }
+  });
+}