dataspring-cli 0.4.4__py3-none-any.whl → 0.5.0__py3-none-any.whl

cli/_skills/dataspring-author/SKILL.md

@@ -13,7 +13,8 @@ affected entity. This skill exists so the conventions stay tight.
 
 Every command and connection acts in ONE org, named each time; nothing
 switches it for later. CLI: `dataspring auth login` prints a URL and a code
-at once (run it in the background and hand both to the person), then
+at once (run it in the background and hand both to the person; they approve
+at their Forspring account and tick the orgs), then
 `--org <org>`, `DATASPRING_ORG`, or `{"org": "<org>"}` in a
 `.forspring.json` at the workspace root, which is the natural place:
 
@@ -21,8 +22,10 @@ at once (run it in the background and hand both to the person), then
 echo '{"org": "acme"}' > .forspring.json && dataspring whoami --json
 ```
 
-MCP: one connection per org, `https://dataspring.app/api/mcp/?org=<org>`, or
-`Authorization: Bearer ds_...` for a headless agent (the key's own org).
+MCP: `claude mcp add --transport http --scope user dataspring
+https://dataspring.app/api/mcp/` (or the same address in any client); the
+person signs in and the consent page names the org, bound to that connection.
+With no person present: `Authorization: Bearer ds_...` (the key's own org).
 
 A refusal leads with a reason and ends with its fix; match the reason. The
 ones you meet while building: `role_too_low` (connections, pipelines,

cli/_skills/dataspring-consume/SKILL.md

@@ -8,8 +8,8 @@ description: How to query DataSpring correctly to answer analytical questions. U
 You are querying DataSpring. Three surfaces are available — pick the
 one the caller is using:
 
-- **MCP** — agent connected to a DataSpring MCP server (Claude
-  Desktop, Claude Code via stdio, etc.). Tool calls.
+- **MCP** — agent connected to DataSpring's MCP server (Claude.ai,
+  Claude Code, Cursor, etc.). Tool calls.
 - **CLI** — `dataspring` from the terminal. Shell commands.
 - **REST** — direct HTTP. Scripts, integrations.
 
@@ -69,22 +69,42 @@ People sign in with their Forspring account; who is in which org, with
 which role, is the account's answer on every request. DataSpring has no
 "current org": every command and every connection names one.
 
-- **CLI.** `dataspring auth login` prints a URL and a code at once and waits
-  until a person approves it in a browser (the machine running the CLI needs
-  none). Run it in the background, hand the person the URL and the code, and
-  wait for it to exit. It stores a `ds_` key for the org they approve
-  (`--all-orgs`: one per org). With one key stored, commands act in that org.
-  With several, name the org on every command, in this order of precedence:
+- **CLI.** `dataspring auth login` prints a URL and a code at once (on
+  stderr) and waits until a person approves it at their Forspring account
+  (`https://account.forspring.ai/device`; the machine running the CLI needs
+  no browser). Run it in the background, hand the person the URL and the
+  code, and wait for it to exit. On the account's page they tick the orgs
+  this CLI may act in; each becomes its own sign-in, kept in
+  `~/.forspring/credentials.json` (shared with the other Forspring CLIs, the
+  tokens in the OS keychain where there is one) for 30 days.
+  `--org <org>` on `auth login` asks for that one org. `ds_` keys an older
+  CLI stored still work. Signed in to one org, commands act in it. With
+  several, name the org on every command, in this order of precedence:
   `--org <org>`, `DATASPRING_ORG` (then `FORSPRING_ORG`), or a
   `.forspring.json` holding `{"org": "<org>"}` in the working directory or a
-  parent. `DATASPRING_API_KEY=ds_...` (CI) acts in the key's own org.
+  parent. `DATASPRING_API_KEY` (CI: a `ds_` key, or an account `fpk_`/`fsa_`
+  key) always wins and acts in the key's own org.
   `dataspring whoami --json` says which org a command here acts in and why
-  (`org_from`). There is no command that switches org for later commands.
-- **MCP.** One connection per org: `https://dataspring.app/api/mcp/?org=<org>`
-  (the slash before `?` is required), signed in with the Forspring account.
-  To work in two orgs, add two connections; no tool moves a connection. A
-  headless agent connects to the same URL with `Authorization: Bearer ds_...`;
-  the key acts in its own org, and `?org=` may only repeat it.
+  (`org_from`: `--org`, `DATASPRING_ORG`, `FORSPRING_ORG`,
+  `.forspring.json`, `key`, `only`) and with what (`credential.kind`:
+  `account`, `legacy` or `env`). There is no command that switches org for
+  later commands. `dataspring auth logout` signs out of the org named (or
+  the only one; `--all` for every one; several and none named is
+  `org_required`). It revokes before it forgets, says "revoked" only when
+  that was confirmed, and otherwise names where to revoke it by hand and
+  exits non-zero.
+- **MCP.** The address is `https://dataspring.app/api/mcp/`, with no org
+  in it. Claude Code: `claude mcp add --transport http --scope user
+  dataspring https://dataspring.app/api/mcp/`, then `/mcp` → *Authenticate*
+  (`claude mcp login dataspring` with no browser); Claude.ai: *Customize →
+  Connectors* → *Add custom connector* with that URL. The person signs in
+  with their Forspring account and DataSpring's consent page names the org
+  the connection works in (their only one, or the one they choose); the
+  choice is bound to the connection. To work in two orgs, add two
+  connections; no tool moves a connection. With no person present (CI), the
+  same address takes `Authorization: Bearer ds_...` (a key made in the
+  console's connect page, under "Automation and CI"): the key acts in its
+  own org, and `?org=` may only repeat it.
 - **REST.** `Authorization: Bearer ds_...`; the key is the org.
 
 Never pick an org for the person. When the org is ambiguous you are refused
@@ -595,13 +615,16 @@ the reason, never on the prose, and pass the fix on verbatim.
 | Reason | CLI exit | What you do |
 |---|---|---|
 | `not_signed_in` | 4 | CLI: run `dataspring auth login` and hand the person its URL and code. MCP: reconnect and sign in. Never ask for a password or a key in chat. |
-| `org_required` | 2 | Several orgs, none named. Ask the person which one (the refusal lists them); then `--org`, `DATASPRING_ORG` or `.forspring.json`. Never guess. |
+| `org_required` | 2 | Several orgs, none named. Ask the person which one (the refusal lists them); then `--org`, `DATASPRING_ORG` or `.forspring.json`. MCP: they reconnect and choose it on the consent page. Never guess. |
 | `not_a_member` | 3 | Check the org id's spelling against the list. Otherwise only an owner or admin of that org can add the person, at the Forspring account; say so and stop. |
 | `product_off` | 4 | DataSpring is not switched on for this person in that org. Tell them who can switch it on (`contacts`, `fix_url`); do not retry. |
 | `org_suspended` | 4 | Billing stopped DataSpring for the whole org. Tell them an owner can restart it on the billing page; do not retry. |
 | `role_too_low` | 4 | Their role cannot do this. Offer what it can do (a personal preference or quick metric instead of an org-wide change), or name the role needed. |
-| `org_mismatch` | 4 | The key or connection is for another org than the one named. Use that org's key or URL, or drop the conflicting `--org` / `?org=`. |
+| `org_mismatch` | 4 | The key or connection (approved for one org) is for another org than the one named. Use that org's key or connection, or drop the conflicting `--org` / `?org=`. |
 | `account_unavailable` | 1 | Forspring's account did not answer, so access could not be checked. Retry once after a few seconds; nothing changed. |
+| `access_denied` | 4 | `auth login`: the person declined in the browser. Ask whether they meant to; run it again only if they say so. |
+| `expired_token` | 5 | `auth login`: the code lapsed (ten minutes) before anyone approved it. Run it again and hand over the new code. |
+| `slow_down` | 7 | `auth login`: too many sign-ins started from this address. Wait, then try again. |
 
 Other CLI exits: 0 success, 1 any other failure, 2 a usage error, 64 a
 removed command (it prints what replaced it).