@gravity-rail/cli 0.36.2 → 0.42.0

package/README.md

@@ -1,6 +1,6 @@
 # @gravity-rail/cli
 
-Command-line interface for [Gravity Rail](https://gravityrail.com) — manage workspaces, AI assistants, conversations, workflows, and 40+ resource types from your terminal.
+Command-line interface for [Gravity Rail](https://gravityrail.com) — manage workspaces, Agents, Chats, Workflows, and other resources from your terminal.
 
 ```
 gr workflows list -w $WORKSPACE
@@ -18,12 +18,6 @@ npx @gravity-rail/cli --help
 
 Requires Node.js 18+.
 
-The published `gr` binary is a single self-contained file. Runtime
-`dependencies` only list packages that exist on the public npm registry
-(`@gravity-rail/sdk`). Build-only monorepo packages such as
-`@gravity-rail/sandbox` (used when compiling code-interpreter bundles) stay in
-`devDependencies` so `npx` / `npm install -g` do not try to fetch them.
-
 ## Authentication
 
 ### OAuth (interactive)
@@ -65,18 +59,6 @@ export GRAVITY_RAIL_PROFILE=work
 
 `gr login` / `gr logout` remain as shortcuts for the active profile (or `--name`).
 
-**Local monorepo / QA (Gravity Rail developers):** after provisioning, import
-dev tokens into the same profile store (this replaces the old `--realm` flag):
-
-```sh
-yarn gr auth import-dev                 # or: python scripts/sync_gr_cli_profiles.py
-yarn gr whoami --profile superadmin
-yarn gr tasks list --profile acme-demo/acme-admin   # auto-sets -w
-```
-
-Workspace/member names use one slash (`workspace/member`). Provisioning auto-syncs
-profiles; re-run import after re-seed. Worktree API ports get isolated credential files.
-
 ### Credential store (security)
 
 | Item            | Detail                                                                                      |
@@ -106,7 +88,7 @@ export GRAVITY_RAIL_API_KEY=your-api-key
 gr tasks list -w $WORKSPACE
 ```
 
-Useful for scripts, CI/CD, and automation. Create scoped keys from workspace settings or via [`@gravity-rail/sdk`](https://www.npmjs.com/package/@gravity-rail/sdk). API keys are **not** written into the profile store.
+Useful for scripts, CI/CD, and automation. Create scoped keys from [Account API Keys](https://docs.gravityrail.com/user-guide/manage/account/api-keys) or via [`@gravity-rail/sdk`](https://www.npmjs.com/package/@gravity-rail/sdk). API keys are **not** written into the profile store.
 
 ### Organizations that require SSO
 
@@ -118,6 +100,25 @@ For **non-interactive** use (CI, scripts, code-interpreter sandboxes, or any mac
 export GRAVITY_RAIL_API_KEY=your-api-key   # set GRAVITY_RAIL_NO_BROWSER=1 to force the API-key hint
 ```
 
+## Search the Documentation
+
+Search without signing in or selecting a Workspace:
+
+```sh
+gr docs search -q "outbound workflow"
+gr docs search -q "webhook signing" -o json
+```
+
+Table output shows page titles and URLs. JSON output includes `title`, `url`, `snippet`, and `score` for each result.
+
+## Work with a Coding Agent
+
+Give an agent the CLI's bootstrap instructions, then use each domain's `--help` to discover its commands:
+
+```sh
+gr get-started --format llm
+```
+
 ## Command Pattern
 
 ```
@@ -147,6 +148,9 @@ The CLI is **read-only by default**. Any command that creates, updates, or delet
 ```sh
 # Reads — no flag needed
 gr members list -w $WORKSPACE
+gr members list -w $WORKSPACE --search "Smith"
+gr members list -w $WORKSPACE --page 2 --page-size 100
+gr members list -w $WORKSPACE --all
 gr workflows get -w $WORKSPACE --id 5
 
 # Writes — must opt in
@@ -189,6 +193,7 @@ Prefer it over `| jq` in scripts and agent tooling: a mistake in the filter is
 reported as a filter error, rather than surfacing as a parse error about output
 you cannot see. It needs the `jq` binary on PATH.
 
+```sh
 # Chain commands
 gr chats list -w $WORKSPACE -o json | jq '.[0].id' | xargs -I{} gr chats get -w $WORKSPACE --id {}
 ```
@@ -287,6 +292,7 @@ not forwarded, as it may contain sensitive data. Use `resume.chatUuid` /
 | `members`     | Contacts and team — CRUD, labels, filters, roles, fields, import/export    |
 | `workspaces`  | Workspace management — CRUD, features, themes, invitations, export/import  |
 | `workflows`   | Conversational workflows — CRUD, notes, contributors, templates, analytics |
+| `journeys`    | Journey definitions — CRUD, V2 authoring, drafts, clone                    |
 | `agents`      | Autonomous AI members — CRUD, archive                                      |
 | `assistants`  | AI personas — CRUD with model and voice configuration                      |
 | `assignments` | Task-based conversations — CRUD, messages, tools                           |
@@ -513,11 +519,180 @@ gr concierge chat --sms --allow-write
 
 If the API returns **412** `account_phone_unverified`, run `gr account verify-phone` first.
 
+## Journey V2 authoring
+
+The same commands are available through the internal `yarn gr` entry point.
+All examples require workspace membership and `journeys:write` (which implies
+`journeys:read`, also checked when cloning).
+
+```sh
+gr journeys create -w $WORKSPACE --data '{"name":"Onboarding V2","executionModel":"v2","status":"draft"}' --allow-write
+gr journeys authoring -w $WORKSPACE --id 42 -o json
+gr journeys v2 put -w $WORKSPACE --id 42 --file definition.json --allow-write
+gr journeys v2 validate -w $WORKSPACE --id 42 -o json
+gr journeys v2 clone -w $WORKSPACE --id 12 --allow-write
+```
+
+`v2 put` replaces the complete executable definition. Include `expectedUpdatedAt`
+from the latest authoring read, ordered `touches`, and `endings`. Each touch can
+carry `eventRules`, an incoming `wait`, and a `branch` with ordered routes.
+Endings carry `celCondition` and/or `filterId` predicates and `eventRules`; they
+need no incoming edge.
+Omitting `goals` preserves them; sending an empty array removes them. A minimal
+`definition.json` is:
+
+```json
+{
+   "expectedUpdatedAt": "2026-09-26T00:00:00Z",
+   "touches": [{ "name": "Welcome", "eventRules": [] }],
+   "endings": []
+}
+```
+
+A branch route can include `memberPredicate`, an unnamed Query IR condition
+owned by the route. For example, this branch selects Members with an email:
+
+```json
+{
+   "routes": [
+      {
+         "name": "Has email",
+         "memberPredicate": {
+            "kind": "compare",
+            "field": "member.email",
+            "op": "notEmpty"
+         }
+      },
+      { "name": "Otherwise", "memberPredicate": null }
+   ]
+}
+```
+
+Use this object as a touch's `branch` in the complete definition. The owned
+predicate is ANDed with any `filterId` and `celCondition`; it creates no saved
+MemberFilter. Reading or changing it additionally requires `members:read` and
+access to its fields. On `v2 put`, omission preserves an existing owned predicate
+and explicit `null` clears it. `v2 validate` reports
+`decision_rule_predicate_invalid` when a stored owned predicate cannot compile.
+
+Existing steps and routes retain identity through their UUIDs. Omit a step or
+route UUID to create it; use request-local `key` values for new rejoin targets.
+EventRules require UUIDs: preserve existing ones when editing, and generate new
+ones when copying actions into another Journey. Read responses are not replacement
+payloads; construct the `touches`/`endings` structure explicitly.
+
+To preserve an unfinished editor document without changing the executable
+Journey, use the separate draft commands:
+
+```sh
+gr journeys v2 draft put -w $WORKSPACE --id 42 --file draft.json --allow-write
+gr journeys authoring -w $WORKSPACE --id 42 -o json
+gr journeys v2 draft delete -w $WORKSPACE --id 42 --expected-updated-at '2026-09-26T00:00:00Z' --allow-write
+```
+
+`draft.json` contains `expectedUpdatedAt` and `document` with `version`, `model`,
+and optional `goalsDirty`. Use the editor's document format. Read it back as
+`authoringDraft` through `journeys authoring`. Discarding that document preserves
+the executable definition. Neither draft command publishes a Journey.
+
+Use `journeys update --id 42 --data '{"status":"active"}' --allow-write` to
+publish, or `status: "paused"` to pause. Publishing runs server validation;
+`v2 validate` reports stored-definition issues without publishing. A stale
+`expectedUpdatedAt` is rejected: reload and reconcile rather than blindly retrying.
+`v2 clone` creates a separate draft from a supported legacy definition and leaves
+the source and enrollments unchanged; unsupported topologies are rejected.
+
 ## Related
 
 - [`@gravity-rail/sdk`](https://www.npmjs.com/package/@gravity-rail/sdk) — TypeScript SDK for programmatic access (500+ methods, full type safety)
-- [Developer Docs](https://developer.gravityrail.com) — Full API reference and guides
+- [Developer Guide](https://docs.gravityrail.com/developer) — Full API reference and guides
 
 ## License
 
 MIT
+
+## Publish and consume reusable Workflows
+
+Author in the owning workspace. `workflows publish` freezes the draft and queues
+its shared release. Bundles are how a published Workflow reaches another
+workspace: `workflows catalog` lists released Workflow and revision UUIDs to pin
+in a Bundle draft.
+
+```sh
+# Publisher
+gr workflows publish -w "$PUBLISHER" --workflow-id "$WORKFLOW" --allow-write
+gr workflows catalog -w "$PUBLISHER" -o json
+gr bundles create -w "$PUBLISHER" --name "Starter Kit" --allow-write
+gr bundles draft set -w "$PUBLISHER" --bundle "$BUNDLE" --file items.json --allow-write
+gr bundles publish -w "$PUBLISHER" --bundle "$BUNDLE" --allow-write
+gr bundles grant -w "$PUBLISHER" --bundle "$BUNDLE" \
+   --to organization --uuid "$ORGANIZATION" --allow-write
+
+# Consumer: installs the latest version, then opts into updates
+gr bundles install -w "$CONSUMER" --bundle "$BUNDLE" --allow-write
+gr bundles policy -w "$CONSUMER" --installation "$INSTALLATION" --set auto --allow-write
+gr bundles readiness -w "$CONSUMER" --installation "$INSTALLATION"
+
+# Make an independent editable copy of an installed Workflow
+gr workflows clone -w "$CONSUMER" --id "$LOCAL_WORKFLOW_ID" \
+   --data '{"name":"My customized Workflow"}' --allow-write
+```
+
+Installation creates the **consumer's local** Workflow ID and UUID; use those for
+consumer reads and copying. Installation and policy changes require
+`workflows:admin` in the destination plus publisher access;
+organization-admin status is not an additional requirement.
+When a Bundle upgrade changes an installed Form schema, the acting administrator
+also needs `datatypes:write` and Form write permission (Form admin permission for
+field-policy changes, including new fields). Missing Form authority or an archived
+Form leaves the held release active and reports that repair is required; it does
+not revoke the Bundle subscription.
+
+### Bundle lifecycle
+
+| Task | Command |
+| --- | --- |
+| Find published Workflow/revision UUIDs for composition | `workflows catalog` |
+| Inspect publisher subscriber versions/policies | `bundles subscribers --bundle <uuid>` |
+| Edit package metadata | `bundles update --bundle <uuid> --name "Starter Kit" --description "Contents"` |
+| Create a package | `bundles create --name "Starter Kit"` |
+| Inspect/edit the package draft | `bundles draft get/set --bundle <uuid>` |
+| Publish an immutable version | `bundles publish --bundle <uuid> --release-notes "What's new"` |
+| Inspect summary and latest content | `bundles get --bundle <uuid>` |
+| Inspect history or one version | `bundles versions/version --bundle <uuid>` |
+| Share within the publisher organization | `bundles grant --bundle <uuid> --to organization --uuid <organization>` |
+| Install the latest version (initially pinned) | `bundles install --bundle <uuid>` |
+| Follow new releases | `bundles policy --installation <uuid> --set auto` |
+| Hold the installed release | `bundles policy --installation <uuid> --set pinned` |
+| Stop updates and keep installed content | `bundles unsubscribe --installation <uuid>` |
+| Preview an upgrade | `bundles preview --installation <uuid> --to 2` |
+| Apply an upgrade | `bundles upgrade --installation <uuid> --to 2` |
+| Inspect missing local dependencies | `bundles readiness --installation <uuid>` |
+| Supply local dependencies | `bundles bind --installation <uuid> --bindings bindings.json` |
+
+Commands require a workspace (`-w` or a workspace profile); mutations also require
+`--allow-write`. Draft item files contain `{ "items": [...] }`; Workflow items
+pin `workflowUuid` and `revisionUuid`, and Form/Site items carry definitions.
+Configuration is reusable software. Records and credentials stay local.
+
+For safe editing, retain `draftGeneration` from `bundles draft get -o json` and
+pass it as `--expected-generation` to `draft set` or `publish`. Omitting it reads
+the current generation just before the write and only detects changes during
+that request sequence. The server's refusal details are preserved.
+
+Use `bundles get --bundle <uuid>` or `bundles install --bundle <uuid>` to reach a
+Bundle by UUID without paging `bundles list`. The Bundle must be visible to the
+workspace: it owns the Bundle, or a live grant names it.
+
+`bundles grant --to organization --uuid <org-uuid>` shares a published Bundle with
+its publishing organization. `bundles grant --to global` shares it with every
+workspace and requires a superuser account. A `draft set` file may carry
+`"links": [{"label", "url"}]`, up to ten named `https` links published with the
+Bundle; a file without `links` keeps the draft's current links.
+
+`bundles get -o json` returns one `{ summary, version }` object; `version` is null
+before publication. Revocations also return JSON when requested. Full UUIDs in
+tables can be copied directly into later commands.
+
+Bundle grants use full source visibility; restricted Bundle disclosure remains
+unavailable while Form and Site definitions are copied at installation.