nimblybase 0.1.0

package/README.md

@@ -0,0 +1,222 @@
+# nimblybase
+
+The NimblyBase command line. Projects, keys and backends from a terminal.
+
+```bash
+npx nimblybase login
+npx nimblybase create "My App"
+npx nimblybase keys create "local dev"
+```
+
+Install it properly if you use it often:
+
+```bash
+npm install -g nimblybase
+nimbly --help
+```
+
+## Signing in
+
+Run:
+
+```bash
+nimbly login
+```
+
+The CLI opens your browser, where you choose the organization and approve
+the requested permissions. The resulting grant is stored in your login
+keychain on macOS, and otherwise in
+`~/.config/nimblybase/credentials.json` with permissions `0600`. `nimbly
+login` always says which one it used.
+
+For a machine without a browser, create an access token in the dashboard
+under **Access tokens** and run `nimbly login --token <token>`. Omitting the
+value prompts without echoing it.
+
+In CI, set `NIMBLYBASE_TOKEN` instead. It takes precedence over anything
+stored and is never written to disk.
+
+## Linking a directory
+
+```bash
+nimbly link my-app
+```
+
+Writes `nimblybase.json`, which records the project id and slug and **no
+credentials**. Commit it: a teammate cloning the repo gets the same target
+without being told a UUID. Commands run anywhere beneath it use that project
+unless you name another with `-p`.
+
+## Scripting
+
+Every command takes `--json`. In JSON mode stdout carries the document and
+nothing else — progress, warnings and errors all go to stderr, including a
+machine-readable error document.
+
+Exit codes are stable:
+
+| code | meaning |
+|---|---|
+| 0 | success |
+| 1 | failed |
+| 2 | bad arguments |
+| 3 | not signed in, or the token is no longer valid |
+| 4 | not found |
+| 5 | refused by permissions |
+| 6 | the API could not be reached |
+
+```bash
+nimbly projects --json | jq -r '.projects[] | select(.status == "active") | .slug'
+```
+
+## Opening a table to your app
+
+The key that ships in a browser — the anon key — can do **nothing** until a
+policy says otherwise. That is the design, not a gap: the alternative is a
+public key that runs arbitrary SQL.
+
+```bash
+nimbly policies                                   # what is open, and to whom
+nimbly policies allow posts select --using true   # let anyone read posts
+nimbly policies allow posts select --using '{"col":"published","eq":true}'
+nimbly policies revoke 3
+```
+
+A table absent from `nimbly policies` is closed entirely — which is almost
+always the answer to "why does my app get nothing back".
+
+An expression is data, not SQL. `{"col":"published","eq":true}` means
+published rows; `{"and":[…]}` and `{"or":[…]}` combine them; and
+`{"col":"owner_id","eq":{"ctx":"userId"}}` means rows belonging to the
+signed-in end user — which matches **nothing** for an anonymous caller, so it
+fails closed rather than open.
+
+`select`, `update` and `delete` need `--using` (which rows may be touched).
+`insert` and `update` need `--check` (which rows may be written).
+
+## Edge functions
+
+```bash
+nimbly functions deploy ./webhook.js
+nimbly functions
+nimbly functions delete webhook
+```
+
+A function is a standard Worker module — `export default { async fetch(request, env) { … } }` —
+published to `https://<ref>.<host>/fn/<name>`.
+
+**The URL is public.** No NimblyBase key is required to call it, because a
+webhook handler that demanded one could not receive a webhook. Check a
+signature or a shared secret inside your own code.
+
+It receives **this project's own resources** and nothing else: `env.DB`,
+`env.FILES`, `env.KV`, and `env.VECTORS` / `env.AI` where the project has
+them. It cannot reach another project's anything, and it does not receive
+the platform-wide bindings our own Worker carries.
+
+## When something is broken
+
+```bash
+nimbly diagnose
+```
+
+Checks, in the order things actually break: is the project serving, does it
+have keys, does the database have tables, does any row policy exist, and what
+has actually been failing in the last day. Prints one sentence, then the
+findings that earned it. Key use is inferred from request logs rather than a
+control-plane timestamp that the edge cannot update.
+
+The commonest answer by a distance is that a table has no policy — which
+makes an anon key get a 403 rather than an empty list.
+
+## Reading as your app reads
+
+`nimbly sql` uses a service key and bypasses policies. `nimbly rows` goes
+through the row API, so it sees what an app sees — which is the only way to
+check a policy actually works.
+
+```bash
+nimbly rows posts --as anon
+nimbly rows posts --as anon --where published=eq.true --order created_at.desc
+nimbly rows posts --as authenticated --as-user u-42
+```
+
+Rows back means the app works. A policy error means it is locked out, and the
+message says which role and which operation.
+
+`--where` is repeatable and takes `<column>=<op>.<value>` — `eq`, `neq`, `gt`,
+`gte`, `lt`, `lte`, `like`, `in`, `is`. Values never go into a string you have
+to quote.
+
+## Logs
+
+```bash
+nimbly logs                      # the last hour
+nimbly logs --level error        # only failures
+nimbly logs --since 24h --route /v1/sql
+```
+
+One line per request: status, method, route, duration, rows read. A failed
+SQL statement is printed underneath its own line, because when it is there it
+is the only thing you want to read.
+
+Newest **last**, so the thing you just did ends up next to your prompt.
+
+Logs are readable while a project is paused — "why did it stop working" is a
+question asked about things that stopped working. They are kept for three
+months, and under heavy load rows are sampled per project; when that happens
+the CLI says so rather than quietly under-reporting.
+
+Never recorded: bound parameters, request or response bodies, credentials, or
+a storage object key in the route column. The SQL statement is recorded only
+when it **failed** — a working application should not accumulate a
+three-month copy of its own query history.
+
+## Connecting an agent
+
+```bash
+nimbly mcp claude --with-token
+```
+
+Prints the exact command or config block for Claude Code, Cursor, VS Code, or
+raw MCP JSON. Without `--with-token` it emits a placeholder, because this
+output is the kind of thing people paste into issues.
+
+## Environment
+
+| variable | effect |
+|---|---|
+| `NIMBLYBASE_TOKEN` | Use this token instead of the stored one |
+| `NIMBLYBASE_API_URL` | Point at a different API |
+| `NIMBLYBASE_NO_KEYCHAIN` | Set to `1` to always use the credentials file |
+| `NO_COLOR` | Disable colour |
+
+## The database
+
+The schema is **declared**, not migrated by hand. You write the shape you
+want; the difference is computed and only the difference runs — which is what
+makes `db push` safe to run twice.
+
+```bash
+nimbly db pull      # write the live schema to schema.json
+$EDITOR schema.json
+nimbly db status    # what push would change, changing nothing
+nimbly db push      # plans, prints the statements, asks, then applies
+```
+
+`db push` **always plans first**, even with `--yes`. Nothing is applied that
+has not been printed. A change that drops a table or column additionally
+needs `--allow-destructive`; `--yes` on its own is consent to run the
+migration, not consent to lose data.
+
+A plan that cannot be carried out completely is refused whole — never applied
+half way.
+
+```bash
+nimbly sql "select * from notes where id = ?" --param 7
+```
+
+`--param` is repeatable and fills the `?` placeholders in order. Values never
+go into the statement string: a CLI whose only option is to paste them in
+teaches everybody — and every agent reading a shell history — to write
+injectable SQL.