@getmagical/cli 0.2.6 → 0.2.8

package/README.md

@@ -108,6 +108,58 @@ These GraphQL operations come from the same shared registry used by the Apollo
 MCP server. MCP callers must provide `idempotencyKey` and
 `expectedTrialCount` directly when starting a run.
 
+## Automation branches
+
+`--branch-id` is a global, per-command authoring target. The CLI never stores a
+current branch. Omit it to target main; branch-aware responses include
+`branchId: null` and the selected main `headVersionId`.
+
+This release adds exactly five commands: branch list, create, get, and merge,
+plus workbench patch readiness.
+
+```bash
+mgcl automations branches list --automation-id <automation-id> --json
+mgcl automations branches create --automation-id <automation-id> --name experiment --json
+mgcl --branch-id <branch-id> automations branches get --automation-id <automation-id> --json
+mgcl --branch-id <branch-id> automations update --id <automation-id> --input-json '{"baseVersionId":"<head-version-id>","name":"Experiment"}' --json
+mgcl --branch-id <branch-id> automations branches merge --automation-id <automation-id> --json
+mgcl --branch-id <branch-id> workbench patch readiness --target-draft-automation-id <automation-id> --operations-json '[{"setAutomationName":{"name":"Experiment readiness preview"}}]' --json
+```
+
+Branch creation defaults to main. Use `--source-branch-id` and optionally
+`--source-version-id` to fork from another branch or an older version in that
+branch's history. Names must use lowercase letters or numbers separated by
+single dashes, such as `release-2`. Spaces, underscores, slashes, backslashes,
+punctuation, uppercase letters, leading or trailing dashes, and repeated dashes
+are rejected before an API request. Branch IDs, not names, identify targets.
+Merge previews the same change set as the web UI. A conflict returns
+`status: "conflict"` and does not change main or delete the branch. A
+conflict-free merge returns `status: "merged"`, the saved-main result, and
+deletes the source branch. Rename, delete, compare, and publish are
+intentionally deferred.
+
+The global branch target is accepted by `automations update`, `automations
+run-draft`, `workbench diagnostics`, `workbench schema-suggestions`, and
+`workbench patch preview`, `readiness`, and `apply`. It is required by
+`automations branches get` and `merge`. Other commands reject `--branch-id`
+before making an API request. Branch-aware responses identify the selected
+target with `branchId` and `headVersionId`. Merge returns `branchId`, its exact
+preview and conflicts, plus the new main head as `applyResult.draftVersionId`
+when successful. Branch inspection excludes workspace authentication records
+and secret values from its hydrated automation response.
+
+For a complete local setup and conflict-free create-to-merge exercise, run the
+commands in [branching-local-test-commands.txt](branching-local-test-commands.txt).
+For a presenter-friendly version that prints every CLI command and pauses for
+approval before merge, run
+[branching-local-demo-commands.txt](branching-local-demo-commands.txt).
+Both scripts derive their service URLs and CLI binary from the current
+worktree, start the tracked portal/main/worker stack, and keep authentication
+in a worktree-local ignored directory. The first run prompts for `mgcl auth
+login`. Set `MGCL_BRANCHING_ORG_ID` to use an organization other than Magical;
+the script headers list the optional namespace, URL, and config-directory
+overrides.
+
 ## Edit a Skill
 
 The Skills working-copy commands currently support root-level skills at