@verentis/cli 0.2.0

package/README.md

@@ -0,0 +1,157 @@
+# @verentis/cli
+
+The Verentis CLI is three tools in one:
+
+1. **Admin** — manage accounts, workspaces, users, invitations, API keys and settings.
+2. **Marketplace publishing** — pack, sign, publish and install `.vpkg` packages.
+3. **Developer loop** — build and debug apps and execution engines **against a real workspace from your local machine**: mint scoped tokens, generate the platform's execution context, run scripts locally with full SDK access, stream execution logs, attach a debugger.
+
+```bash
+npm install -g @verentis/cli
+```
+
+## Sign in
+
+```bash
+verentis login --api-url https://api.verentis.dev
+```
+
+With no credential flags this starts a **device sign-in**: open the printed URL in any browser (works over SSH), confirm the code, done. Non-interactive alternatives:
+
+```bash
+verentis login --api-url … --api-key vrt_xxx     # CI / scripts (create one with `verentis apikey create`)
+verentis login --api-url … --token <identity token>
+# VERENTIS_API_URL / VERENTIS_API_KEY / VERENTIS_TOKEN env vars also work
+```
+
+Set defaults once so you can stop repeating flags:
+
+```bash
+verentis use workspace <workspaceId>
+verentis use account <accountId>
+verentis context        # show current defaults
+verentis whoami         # identity, account, publisher
+```
+
+## Admin
+
+```bash
+verentis workspace list
+verentis workspace create "My Workspace" --use
+verentis workspace invite create <workspaceId> dev@example.com --role member
+verentis account invite list
+verentis user list --workspace <id>
+verentis user suspend <userId>
+verentis apikey create ci-key --grant node.file.read --grant execution.execution.run
+verentis apikey revoke <apiKeyId>
+verentis settings set my.setting '{"enabled":true}' --workspace <id>
+```
+
+Anything without a dedicated command is one escape hatch away (auth handled for you):
+
+```bash
+verentis api GET /v1/roles --scope security.role.read-all
+verentis api POST /v1/things --body @thing.json --workspace <id> --scope some.scope
+```
+
+## Workspace files
+
+```bash
+verentis files ls /scripts
+verentis files cat /data/input.json
+verentis files upload ./local-dir /scripts          # recursive
+verentis files upload build.zip /apps --extract     # server-side archive extraction
+verentis files download /data/report.json
+verentis files mv /a.txt /archive/a.txt
+verentis files rm /tmp-dir --recursive
+```
+
+All file commands take `--branch` (default `main`) and `--workspace`.
+
+## Executions
+
+```bash
+verentis exec run /scripts/transform.py --follow          # run remotely, stream logs live
+verentis exec run /scripts/etl.py --arg --verbose --params '{"rows":10}'
+verentis exec list
+verentis exec logs <executionId> --follow                 # SSE log streaming
+verentis exec cancel <executionId>
+verentis engine list
+verentis engine resolve text/x-python
+```
+
+## The developer loop
+
+Write engine/app scripts locally, but read and write **real workspace files** through the [`verentis-engine-sdk`](https://pypi.org/project/verentis-engine-sdk/) — exactly like a platform run:
+
+```bash
+cd my-engine-project        # has an engine.yaml with spec.permissions
+
+# Run a local script with a real scoped token + injected context —
+# engine.files / engine.http hit the actual workspace:
+verentis dev run transform.py --workspace <id> --params '{"message":"hi"}'
+
+# Debug: waits for your debugger before the first line runs
+verentis dev run transform.py --debug          # debugpy on :5678, --wait-for-client
+verentis dev vscode                            # scaffolds .vscode/launch.json (attach + launch)
+```
+
+Lower-level building blocks:
+
+```bash
+verentis dev token --workspace <id>                    # scopes from ./engine.yaml spec.permissions
+verentis dev token --scopes node.file.read --boundary /scripts   # node-bounded, like platform runs
+verentis dev context --file /scripts/transform.py --out .verentis/context.json
+export VERENTIS_CONTEXT_PATH=$PWD/.verentis/context.json
+python transform.py                                    # SDK auto-loads the context
+
+verentis validate engine.yaml                          # manifest checks before publish
+```
+
+`dev run` writes `.verentis/context.json` (mode 600 — contains a short-lived token; git-ignore `.verentis/`).
+
+## Marketplace publishing
+
+```bash
+verentis publisher create --name acme --display-name "Acme Inc."
+verentis keygen                        # Ed25519 signing key + register public half
+verentis init my-app --kind application
+verentis pack                          # signed .vpkg (--encrypt seals the payload)
+verentis publish my-app-0.1.0.vpkg
+verentis package list                  # your packages
+verentis package versions acme/my-app
+verentis package deprecate my-app --message "use my-app-2"
+verentis package visibility set my-app Private
+verentis package visibility grant my-app <workspaceId>
+verentis package stats my-app
+verentis search "image viewer" --kind Application
+verentis install acme/my-app --workspace <id>
+verentis installs --workspace <id>
+verentis uninstall <installationId> --workspace <id>
+verentis yank my-app 1.0.3
+```
+
+Published versions are `Submitted` for moderation; once approved the marketplace countersigns them and they become installable.
+
+## The `.vpkg` format
+
+A gzip tarball: `manifest.yaml` + `files/**` payload + `.verentis/` metadata (package.yaml, sha256 digests, DSSE signatures). Manifest references like `./schemas/x.json` resolve against `files/` — and against the children of the installed manifest node after installation. See the platform docs (`marketplace/packaging`) for the full specification.
+
+Packing behaviour:
+- `packaging.files` globs select the payload; without them, applications automatically include every `./…` schema `source` referenced by the manifest.
+- Digests cover every payload entry; the registry rejects tampered packages.
+- With a configured signing key the digests document is DSSE-signed (Ed25519). Publishers with registered keys **must** sign uploads.
+- `pack --encrypt` seals the payload (AES-256-GCM, X25519 key wrapping per recipient — always including the `platform` escrow recipient so Verentis.Node can serve member reads).
+
+## Output & scripting
+
+Most read commands accept `--json` for machine-readable output, plus `--page/--page-size/--order-by` on paged listings. Errors render RFC 7807 problem details compactly.
+
+## Development
+
+```bash
+npm install
+npm test        # vitest
+npm run build   # tsup → dist/
+```
+