@dashai/cli 0.18.3 → 0.20.0

package/README.md

@@ -67,6 +67,155 @@ Show the current user + accessible workspaces. Refreshes the cached profile from
 Flags:
 - `--json` — Emit a single JSON object `{ ok, user, default_workspace, workspaces, api_url }` for piping into CI / `jq`.
 
+### `dashwise mcp` / `dashwise mcp add`
+
+Run a local MCP server for one workspace, so Claude can read and write your Dashwise data.
+
+```bash
+# Register it with Claude Code, once, per machine:
+dashwise mcp add --workspace acme
+
+# What that registration runs (you never type this yourself):
+dashwise mcp --workspace acme
+
+# The same server with a narrowed key: rows of table 412, read-only, enforced by the server:
+dashwise mcp --workspace acme --scope datahub:table=412:r
+
+# Register that narrowed form, so every session Claude Code starts carries the grant:
+dashwise mcp add --workspace acme --grant-scope datahub:table=412:r
+```
+
+`dashwise mcp` is short for `dashwise mcp serve`, and `dashwise mcp serve --help` lists the flags below.
+
+**Or install the plugin instead.** `plugins/dashwise/` in this repository is a Claude
+Code plugin that registers this same server, ships the `dashwise-data` and
+`dashwise-module-builder` skills with it, and adds a hook that refuses to let a
+`dwk_`, `dwc_` or `dwm_` credential reach the transcript. One install replaces
+`mcp add` plus the manual skill copy. `dashwise agent setup` (below) runs it for you,
+or by hand:
+
+```bash
+claude plugin marketplace add Intuize/dashwise-cli
+claude plugin install dashwise
+```
+
+The plugin is **for Dashwise staff only, for now**: `Intuize/dashwise-cli` is a private
+repository, so the `marketplace add` fails for anyone who cannot read it. Everyone else
+connects with `dashwise mcp add`, which needs no plugin.
+
+`plugins/dashwise/README.md` covers prerequisites, what the hook blocks, and how to
+turn it off. `dashwise mcp add` remains the right answer when you want the server
+without the skill or the hook.
+
+**Why this exists.** The other way to connect Claude is to paste a URL that *contains* the
+credential. That URL then lives in `~/.claude.json`, in your shell history, and in the screenshot
+you attach to a support ticket. `dashwise mcp` exchanges your `dashwise login` token for an
+endpoint key at startup, keeps it in the process's memory, and drops it on exit. Nothing is written
+to disk, nothing is printed, and `--verbose` logs frame *types and sizes* — never bodies, never the
+key.
+
+`dashwise mcp` speaks MCP over stdio and relays every frame to the workspace's Streamable HTTP
+endpoint. It is a pipe: a protocol change on the server needs no CLI release.
+
+Flags for `dashwise mcp` (`serve`):
+- `--workspace <slug>` — which workspace to connect. Defaults to `dashwise workspace use`; with one
+  workspace, it is picked for you.
+- `--scope <grant>` — narrow this session's key; **the server enforces it**. Repeat the flag to add
+  grants, and they add up: `datahub:table=<id>:<ops>`, `datahub:app=<id>:<ops>`,
+  `datahub:workspace:<ops>` (ops are one to four of `c`, `r`, `u`, `d`) or
+  `governance:workspace:r`. A scope only narrows. Every grant must be within your own access, and
+  one that is not is refused with the server's reason (`SCOPE_EXCEEDS_CREATOR_ACCESS`). At startup
+  the CLI prints the scopes as the server stored them. The server merges grants on one target, so
+  that line can read differently from the flags. If a server mints the session without confirming
+  the scopes, the CLI revokes it and exits 1, because running it would hand over an un-narrowed
+  key. Without `--scope` the key reaches what your account can. A backend older than this flag
+  refuses the field, and the CLI says so.
+- `--endpoint-name <label>` — label for this machine (default: your hostname). Each run gets its
+  own endpoint, named `dashwise-cli@<label>#<id>` in the Dashwise endpoints panel; the server adds
+  the short id so two sessions on one machine can be told apart, and an admin can revoke either of
+  them. Running Claude Code and Claude Desktop side by side needs no special handling — they get
+  separate endpoints and neither disturbs the other.
+- `--read-only` — refuse write tools. **This is a client-side guard**: the proxy declines the call,
+  and the server is not told. It prevents accidents, which is most of what it is for; it is not a
+  fence. For a limit the server enforces, use `--scope` (for example `--scope datahub:workspace:r`).
+- `--verbose` — log frame types and sizes to stderr.
+
+Flags for `dashwise mcp add` (`--workspace`, `--read-only` and `--endpoint-name` as above, plus):
+- `--name <server-name>` — the name Claude Code shows (default: `dashwise`).
+- `--scope local|project|user` — **Claude Code's** config scope: where the registration
+  is saved (default: `local`). It says nothing about what the key can reach.
+- `--grant-scope <grant>` — the **server's** grant scope, written into the registration
+  as `dashwise mcp --scope <grant>`, so every session started from it is narrowed on
+  the server. Repeatable, same grammar as `--scope` on `dashwise mcp` above, and checked
+  before anything is registered. On `add`, `--scope` was already taken by Claude Code's
+  option, which is why the grant has its own name here:
+
+  ```bash
+  dashwise mcp add --workspace acme --scope user --grant-scope datahub:app=7:r --grant-scope governance:workspace:r
+  # registers: claude mcp add dashwise --scope user -- dashwise mcp --workspace acme --scope datahub:app=7:r --scope governance:workspace:r
+  ```
+
+`mcp add` shells out to `claude mcp add` and prints the exact command it runs. If `claude` is not on
+your `PATH`, that printed command is the whole remedy — copy it once Claude Code is installed.
+
+**Session lifetime.** Each `dashwise mcp` process owns one endpoint. It revokes that endpoint when
+it exits cleanly (the client closing it, `^C`, or a `SIGTERM`), and the endpoint expires after 24
+hours regardless — so a session left behind by a crash or a hard kill dies the same day rather than
+lingering as a live credential.
+
+**Revoking a session.** Open the Dashwise endpoints panel, find the `dashwise-cli@…` row you want,
+and revoke it. That session stops immediately. Starting `dashwise mcp` again gives you a new
+endpoint, which is the intended way back — revoking is about killing the session that is running,
+not about locking the machine out.
+
+### `dashwise agent setup`
+
+Install the Dashwise plugin into Claude Code in one command: the skills, the `dashwise`
+MCP server and the secrets guard. **Staff only, for now:** its default source is a
+private repository, so step 3 fails for anyone who cannot read it (see above).
+
+```bash
+dashwise agent setup            # adds the marketplace if needed, then installs dashwise@dashwise
+dashwise agent setup --status   # what is installed; changes nothing
+```
+
+What it runs, in order:
+
+1. `claude --version`. If Claude Code is not on your `PATH`, it prints the two
+   commands below and exits 0. Nothing is installed.
+2. `claude plugin list --json`. If `dashwise@dashwise` is already installed, it says
+   so and stops.
+3. `claude plugin marketplace list --json`, then `claude plugin marketplace add
+   <source>`, but only when no marketplace named `dashwise` is configured.
+4. `claude plugin install dashwise@dashwise`.
+
+The two calls that change something run in your terminal, so you see Claude Code's
+own output. If either fails, the command exits with its code and prints the
+commands that finish the job by hand:
+
+```bash
+claude plugin marketplace add Intuize/dashwise-cli
+claude plugin install dashwise@dashwise
+```
+
+Flags:
+- `--marketplace <source>`: the marketplace to add. It takes anything `claude plugin
+  marketplace add` accepts: owner/repo, a git URL, a local path, a URL. The default
+  is `Intuize/dashwise-cli`, this repository, and it moves to the public plugin
+  repository once that exists. A `dashwise` marketplace already configured from
+  somewhere else is not replaced; the command says how to remove it.
+- `--status`: report whether the marketplace is configured and the plugin installed
+  (version, scope, enabled or disabled), and change nothing. It exits 1 when Claude
+  Code's answer cannot be read, rather than guessing "not installed". With no `claude`
+  on your `PATH` it says Claude Code is not installed, and exits 0.
+- `--json`: print one JSON object on stdout and nothing else. With it, Claude Code's
+  own output is captured rather than shown.
+
+Nothing runs this for you. No other command, `dashwise login` included, calls it or
+suggests it. Afterwards, restart Claude Code, and if you have never run
+`dashwise login` on this machine, run it once. The plugin's MCP server needs it, and
+the plugin's session-start note will say so if you forget.
+
 ### `dashwise workspace list`
 
 List workspaces the user belongs to. The default workspace (set via `workspace use`) is marked with `*`.