buildx-cli 1.8.17 → 1.8.19

package/README.md

@@ -160,6 +160,12 @@ Lists available projects for the authenticated account.
 npx buildx-cli projects:list
 ```
 
+Filter by product key (`project.product.key`):
+
+```bash
+npx buildx-cli projects:list --product-key approval
+```
+
 #### `projects:set-default <project-id>`
 Sets default project used by commands when `--project-id` is not provided.
 
@@ -333,6 +339,7 @@ Behavior:
 
 Key options:
 - `-p, --project-id <id>`
+- `--product-key <key>` push to all projects where `project.product.key` matches (cannot be used with `--project-id`)
 - `-t, --target-dir <path>`
 - `--collections-file <path>` (when no `--target-dir`)
 - `--filter <pattern...>`
@@ -341,6 +348,7 @@ Key options:
 
 ```bash
 npx buildx-cli schema:push --project-id hello-world --target-dir ./.sandbox/buildx-cli --dry-run
+npx buildx-cli schema:push --product-key approval --target-dir ./.sandbox/buildx-cli --dry-run
 ```
 
 #### `schema:types:convert`
@@ -478,6 +486,7 @@ Behavior:
 
 Key options:
 - `-p, --project-id <id>`
+- `--product-key <key>` push to all projects where `project.product.key` matches (cannot be used with `--project-id`)
 - `-t, --target-dir <path>`
 - `--functions-dir <path>` (when no `--target-dir`)
 - `-n, --name <function-name>` for a single function
@@ -489,6 +498,7 @@ Key options:
 
 ```bash
 npx buildx-cli function:push --project-id hello-world --target-dir ./.sandbox/buildx-cli --dry-run
+npx buildx-cli function:push --product-key approval --target-dir ./.sandbox/buildx-cli --dry-run
 ```
 
 #### `function:list`
@@ -539,8 +549,8 @@ Key options:
 npx buildx-cli function:revisions process-order --project-id hello-world
 ```
 
-#### `function:publish <function-name> <revision>`
-Publishes a revision to live (or custom alias).
+#### `function:publish <function-name> [revision]`
+Publishes a revision to alias (default alias: `live`). If `revision` is omitted, CLI publishes the latest revision.
 
 Key options:
 - `-p, --project-id <id>`
@@ -548,10 +558,41 @@ Key options:
 - `--alias <alias>` (default: `live`)
 
 ```bash
+npx buildx-cli function:publish process-order --project-id hello-world
 npx buildx-cli function:publish process-order r12 --project-id hello-world
 npx buildx-cli function:publish process-order 12 --project-id hello-world --alias stable
 ```
 
+Best practices:
+- Use aliases as stable pointers for environments/traffic, not raw revision numbers in app code.
+- Revision identifier is system-managed (`r1`, `r2`, ...). You cannot set revision id manually.
+- If you want deployment traceability by git commit, use git hash as an alias (for example: `a1b2c3d4` -> `r42`).
+- Recommended alias convention:
+  - `live`: production traffic
+  - `stable`: last known good release
+  - `canary`: limited rollout / verification
+- Typical release flow:
+  1. Save function in Studio/CLI (creates new revision automatically)
+  2. Validate with `function:invoke --revision rN`
+  3. Promote by alias: `function:alias:set <fn> canary rN`
+  4. Promote to production: `function:publish <fn> rN --alias live`
+  5. Fast rollback: `function:alias:set <fn> live <previous-revision>`
+- For routine publish operations, run `function:publish <fn>` without revision to move the latest revision to `live`.
+- Keep revision IDs immutable and treat alias changes as deployment events (track in release notes/ops logs).
+- Use `function:revisions <fn>` to list revision id, checksum (short), and alias mapping in one place.
+
+Git-hash alias example:
+```bash
+# Point alias named by git hash to a revision
+npx buildx-cli function:alias:set process-order a1b2c3d4 r42 --project-id hello-world
+
+# Publish latest revision to a git-hash alias
+npx buildx-cli function:publish process-order --project-id hello-world --alias a1b2c3d4
+
+# Inspect mapping + checksum
+npx buildx-cli function:revisions process-order --project-id hello-world
+```
+
 #### `function:alias:set <function-name> <alias> <revision>`
 Sets alias pointer directly to a revision.
 
@@ -638,6 +679,159 @@ The CLI interacts with the following API endpoints:
 - `GET /project/:project_id/functions` - List functions
 - `GET /project/:project_id/functions/:function_name` - Fetch function source
 - `POST /project/:project_id/functions/:function_name` - Upsert function source
+- `GET /project/:project_id/functions/:function_name/revisions` - List function revisions
+- `POST /project/:project_id/functions/:function_name/revisions/:revision/publish` - Publish function revision
+- `PUT /project/:project_id/functions/:function_name/aliases/:alias` - Update function alias
+- `POST /project/:project_id/functions/run/:function_name` - Invoke function
+
+## CLI Output Formats (All Commands)
+
+Detailed command-by-command examples (normal + `--json`): see [OUTPUT_EXAMPLES.md](./OUTPUT_EXAMPLES.md).
+
+General rules:
+- Success output is human-readable by default unless command has explicit JSON mode.
+- Error output is plain text: `Error: <message>` and exits non-zero.
+- Commands with `--json` print JSON to stdout for automation.
+- Commands that return documents (`data:list/get/create/update/delete`) are already JSON by default.
+
+### Authentication
+- `auth:login`:
+  - default: human-readable status lines
+  - `--json`: `{ success, method, username, tokenMasked, expiresAt }`
+- `auth:logout`:
+  - default: human-readable confirmation
+  - `--json`: `{ success, authenticated }`
+- `auth:status`:
+  - default: human-readable session summary
+  - `--json`: `{ success, authenticated, user?, tokenMasked?, expiresAt? }`
+
+### Projects
+- `projects:list`:
+  - default: human-readable list
+  - `--json`: `{ success, projects[], total, defaultProjectId }`
+- `projects:set-default`:
+  - default: human-readable confirmation
+  - `--json`: `{ success, defaultProjectId, project }`
+- `projects:current`:
+  - default: human-readable summary
+  - `--json`: `{ success, defaultProject }`
+- `projects:metadata:get`: prints pretty JSON for selected metadata path.
+  - `--output <file>` writes JSON file and prints success line.
+- `projects:metadata:update`:
+  - default: human-readable summary (`default_language`, `timezone`, key count)
+  - `--json`: updated project payload JSON
+  - `--dry-run`: payload JSON only
+- `projects:locale:validate`: success line + JSON validation result.
+
+### Configuration
+- `config:setup`:
+  - default: interactive + human-readable summary
+  - `--json`: `{ success, api: { endpoint, apiKeyMasked } }`
+- `config:show`:
+  - default: human-readable configuration report
+  - `--json`: structured config payload (`api`, `auth`, `projects`, `sync`, `configPath`, `envSources`)
+- `config:clear`:
+  - default: human-readable confirmation
+  - `--json`: `{ success, cleared }`
+
+### Users
+- `user:list`:
+  - default: tab-separated table (`id`, `username`, `name`, `email`) + total
+  - `--json`: raw users array JSON
+- `user:create`:
+  - default: human-readable confirmation
+  - `--json`: created user JSON
+
+### Schema
+- `schema:pull` / `schema:sync`:
+  - default: file write summary
+  - `--dry-run`: file preview blocks (JSON/text)
+  - `--json`: `{ success, command, project_id, output, dryRun }`
+- `schema:push`:
+  - default: per-collection lines + `pushed/skipped` summary
+  - `--json`: `{ success, pushed, skipped, results[] }`
+- `schema:list`:
+  - default: one `collection_id` per line + total
+  - `--json`: `{ success, total, collections[] }`
+- `schema:diff` markers:
+  - `= same`
+  - `~ changed`
+  - `+ local-only`
+  - `- remote-only`
+  - `--json`: `{ success, summary, results[] }`
+- `schema:types:convert`:
+  - default: conversion summary + output path
+  - `--dry-run`: generated JSON preview
+  - `--json`: `{ success, dryRun, output, collections_count, warnings[] }`
+
+### Functions
+- `function:pull` / `function:sync`:
+  - default: file write summary
+  - `--dry-run`: context/source/manifest preview blocks
+  - `--json`: `{ success, command, project_id, output, dryRun }`
+- `function:push`:
+  - default: per-function lines + `pushed/skipped` summary
+  - `--dry-run`: would-push + manifest preview
+  - `--json`: `{ success, pushed, skipped, results[] }`
+- `function:list`:
+  - default: one function name per line + total
+  - `--json`: `{ success, total, functions[] }`
+- `function:logs`:
+  - default: `timestamp status message` lines + shown count
+  - `--json`: raw log rows JSON
+- `function:diff` markers:
+  - `= same`
+  - `~ changed`
+  - `+ local-missing`
+  - `- remote-missing`
+  - `! remote-drift`
+  - `--json`: `{ success, summary, results[] }`
+- `function:revisions`:
+  - default: one line per revision with
+    - live marker (`[live]`)
+    - `revision` + `revision_id`
+    - short checksum (`source_checksum` first 12 chars)
+    - `createdAt`
+    - alias mapping (`aliases=...`)
+  - `--json`: array entries with keys:
+    - `revision`
+    - `revision_id`
+    - `checksum`
+    - `createdAt`
+    - `live`
+    - `aliases`
+- `function:publish`:
+  - default: confirmation + live revision + aliases object
+  - `[revision]` omitted => auto uses latest revision
+  - `--json`: `{ success, function, publishedRevision, alias, live_revision_id, aliases }`
+- `function:alias:set`:
+  - default: confirmation line with alias target
+  - `--json`: `{ success, function, alias, revision, aliases }`
+- `function:invoke`:
+  - object/array response: pretty JSON
+  - text response: plain text
+  - `--raw`: raw response output
+
+### Data
+- `data:list`: pretty JSON response.
+- `data:get`: pretty JSON response.
+- `data:create`: pretty JSON response.
+- `data:update`: pretty JSON response.
+- `data:delete`: pretty JSON response.
+- `data:export`: writes JSON file + summary line.
+  - `--json`: `{ success, collection_id, project_id, count, output }`
+- `data:import`:
+  - default: summary (`created`, `updated`)
+  - `--dry-run`: simulated summary lines
+  - `--json`: structured import result (`success`, `collection_id`, `project_id`, `mode`, `batch`, `dryRun`, `created`, `updated`, `match?`)
+
+### Revision/Alias Definition (Important)
+- Function revision is system-managed and immutable (`r1`, `r2`, ...).
+- You cannot set custom revision id (for example git hash) as revision.
+- If you need git-traceable deployment labels, use alias names as git hash values.
+- Example:
+  - `function:alias:set process-order a1b2c3d4 r42`
+  - `function:revisions process-order` (to inspect mapping + checksum)
 
 ## Development
 

package/dist/README.md

@@ -160,6 +160,12 @@ Lists available projects for the authenticated account.
 npx buildx-cli projects:list
 ```
 
+Filter by product key (`project.product.key`):
+
+```bash
+npx buildx-cli projects:list --product-key approval
+```
+
 #### `projects:set-default <project-id>`
 Sets default project used by commands when `--project-id` is not provided.
 
@@ -333,6 +339,7 @@ Behavior:
 
 Key options:
 - `-p, --project-id <id>`
+- `--product-key <key>` push to all projects where `project.product.key` matches (cannot be used with `--project-id`)
 - `-t, --target-dir <path>`
 - `--collections-file <path>` (when no `--target-dir`)
 - `--filter <pattern...>`
@@ -341,6 +348,7 @@ Key options:
 
 ```bash
 npx buildx-cli schema:push --project-id hello-world --target-dir ./.sandbox/buildx-cli --dry-run
+npx buildx-cli schema:push --product-key approval --target-dir ./.sandbox/buildx-cli --dry-run
 ```
 
 #### `schema:types:convert`
@@ -478,6 +486,7 @@ Behavior:
 
 Key options:
 - `-p, --project-id <id>`
+- `--product-key <key>` push to all projects where `project.product.key` matches (cannot be used with `--project-id`)
 - `-t, --target-dir <path>`
 - `--functions-dir <path>` (when no `--target-dir`)
 - `-n, --name <function-name>` for a single function
@@ -489,6 +498,7 @@ Key options:
 
 ```bash
 npx buildx-cli function:push --project-id hello-world --target-dir ./.sandbox/buildx-cli --dry-run
+npx buildx-cli function:push --product-key approval --target-dir ./.sandbox/buildx-cli --dry-run
 ```
 
 #### `function:list`
@@ -539,8 +549,8 @@ Key options:
 npx buildx-cli function:revisions process-order --project-id hello-world
 ```
 
-#### `function:publish <function-name> <revision>`
-Publishes a revision to live (or custom alias).
+#### `function:publish <function-name> [revision]`
+Publishes a revision to alias (default alias: `live`). If `revision` is omitted, CLI publishes the latest revision.
 
 Key options:
 - `-p, --project-id <id>`
@@ -548,10 +558,41 @@ Key options:
 - `--alias <alias>` (default: `live`)
 
 ```bash
+npx buildx-cli function:publish process-order --project-id hello-world
 npx buildx-cli function:publish process-order r12 --project-id hello-world
 npx buildx-cli function:publish process-order 12 --project-id hello-world --alias stable
 ```
 
+Best practices:
+- Use aliases as stable pointers for environments/traffic, not raw revision numbers in app code.
+- Revision identifier is system-managed (`r1`, `r2`, ...). You cannot set revision id manually.
+- If you want deployment traceability by git commit, use git hash as an alias (for example: `a1b2c3d4` -> `r42`).
+- Recommended alias convention:
+  - `live`: production traffic
+  - `stable`: last known good release
+  - `canary`: limited rollout / verification
+- Typical release flow:
+  1. Save function in Studio/CLI (creates new revision automatically)
+  2. Validate with `function:invoke --revision rN`
+  3. Promote by alias: `function:alias:set <fn> canary rN`
+  4. Promote to production: `function:publish <fn> rN --alias live`
+  5. Fast rollback: `function:alias:set <fn> live <previous-revision>`
+- For routine publish operations, run `function:publish <fn>` without revision to move the latest revision to `live`.
+- Keep revision IDs immutable and treat alias changes as deployment events (track in release notes/ops logs).
+- Use `function:revisions <fn>` to list revision id, checksum (short), and alias mapping in one place.
+
+Git-hash alias example:
+```bash
+# Point alias named by git hash to a revision
+npx buildx-cli function:alias:set process-order a1b2c3d4 r42 --project-id hello-world
+
+# Publish latest revision to a git-hash alias
+npx buildx-cli function:publish process-order --project-id hello-world --alias a1b2c3d4
+
+# Inspect mapping + checksum
+npx buildx-cli function:revisions process-order --project-id hello-world
+```
+
 #### `function:alias:set <function-name> <alias> <revision>`
 Sets alias pointer directly to a revision.
 
@@ -638,6 +679,159 @@ The CLI interacts with the following API endpoints:
 - `GET /project/:project_id/functions` - List functions
 - `GET /project/:project_id/functions/:function_name` - Fetch function source
 - `POST /project/:project_id/functions/:function_name` - Upsert function source
+- `GET /project/:project_id/functions/:function_name/revisions` - List function revisions
+- `POST /project/:project_id/functions/:function_name/revisions/:revision/publish` - Publish function revision
+- `PUT /project/:project_id/functions/:function_name/aliases/:alias` - Update function alias
+- `POST /project/:project_id/functions/run/:function_name` - Invoke function
+
+## CLI Output Formats (All Commands)
+
+Detailed command-by-command examples (normal + `--json`): see [OUTPUT_EXAMPLES.md](./OUTPUT_EXAMPLES.md).
+
+General rules:
+- Success output is human-readable by default unless command has explicit JSON mode.
+- Error output is plain text: `Error: <message>` and exits non-zero.
+- Commands with `--json` print JSON to stdout for automation.
+- Commands that return documents (`data:list/get/create/update/delete`) are already JSON by default.
+
+### Authentication
+- `auth:login`:
+  - default: human-readable status lines
+  - `--json`: `{ success, method, username, tokenMasked, expiresAt }`
+- `auth:logout`:
+  - default: human-readable confirmation
+  - `--json`: `{ success, authenticated }`
+- `auth:status`:
+  - default: human-readable session summary
+  - `--json`: `{ success, authenticated, user?, tokenMasked?, expiresAt? }`
+
+### Projects
+- `projects:list`:
+  - default: human-readable list
+  - `--json`: `{ success, projects[], total, defaultProjectId }`
+- `projects:set-default`:
+  - default: human-readable confirmation
+  - `--json`: `{ success, defaultProjectId, project }`
+- `projects:current`:
+  - default: human-readable summary
+  - `--json`: `{ success, defaultProject }`
+- `projects:metadata:get`: prints pretty JSON for selected metadata path.
+  - `--output <file>` writes JSON file and prints success line.
+- `projects:metadata:update`:
+  - default: human-readable summary (`default_language`, `timezone`, key count)
+  - `--json`: updated project payload JSON
+  - `--dry-run`: payload JSON only
+- `projects:locale:validate`: success line + JSON validation result.
+
+### Configuration
+- `config:setup`:
+  - default: interactive + human-readable summary
+  - `--json`: `{ success, api: { endpoint, apiKeyMasked } }`
+- `config:show`:
+  - default: human-readable configuration report
+  - `--json`: structured config payload (`api`, `auth`, `projects`, `sync`, `configPath`, `envSources`)
+- `config:clear`:
+  - default: human-readable confirmation
+  - `--json`: `{ success, cleared }`
+
+### Users
+- `user:list`:
+  - default: tab-separated table (`id`, `username`, `name`, `email`) + total
+  - `--json`: raw users array JSON
+- `user:create`:
+  - default: human-readable confirmation
+  - `--json`: created user JSON
+
+### Schema
+- `schema:pull` / `schema:sync`:
+  - default: file write summary
+  - `--dry-run`: file preview blocks (JSON/text)
+  - `--json`: `{ success, command, project_id, output, dryRun }`
+- `schema:push`:
+  - default: per-collection lines + `pushed/skipped` summary
+  - `--json`: `{ success, pushed, skipped, results[] }`
+- `schema:list`:
+  - default: one `collection_id` per line + total
+  - `--json`: `{ success, total, collections[] }`
+- `schema:diff` markers:
+  - `= same`
+  - `~ changed`
+  - `+ local-only`
+  - `- remote-only`
+  - `--json`: `{ success, summary, results[] }`
+- `schema:types:convert`:
+  - default: conversion summary + output path
+  - `--dry-run`: generated JSON preview
+  - `--json`: `{ success, dryRun, output, collections_count, warnings[] }`
+
+### Functions
+- `function:pull` / `function:sync`:
+  - default: file write summary
+  - `--dry-run`: context/source/manifest preview blocks
+  - `--json`: `{ success, command, project_id, output, dryRun }`
+- `function:push`:
+  - default: per-function lines + `pushed/skipped` summary
+  - `--dry-run`: would-push + manifest preview
+  - `--json`: `{ success, pushed, skipped, results[] }`
+- `function:list`:
+  - default: one function name per line + total
+  - `--json`: `{ success, total, functions[] }`
+- `function:logs`:
+  - default: `timestamp status message` lines + shown count
+  - `--json`: raw log rows JSON
+- `function:diff` markers:
+  - `= same`
+  - `~ changed`
+  - `+ local-missing`
+  - `- remote-missing`
+  - `! remote-drift`
+  - `--json`: `{ success, summary, results[] }`
+- `function:revisions`:
+  - default: one line per revision with
+    - live marker (`[live]`)
+    - `revision` + `revision_id`
+    - short checksum (`source_checksum` first 12 chars)
+    - `createdAt`
+    - alias mapping (`aliases=...`)
+  - `--json`: array entries with keys:
+    - `revision`
+    - `revision_id`
+    - `checksum`
+    - `createdAt`
+    - `live`
+    - `aliases`
+- `function:publish`:
+  - default: confirmation + live revision + aliases object
+  - `[revision]` omitted => auto uses latest revision
+  - `--json`: `{ success, function, publishedRevision, alias, live_revision_id, aliases }`
+- `function:alias:set`:
+  - default: confirmation line with alias target
+  - `--json`: `{ success, function, alias, revision, aliases }`
+- `function:invoke`:
+  - object/array response: pretty JSON
+  - text response: plain text
+  - `--raw`: raw response output
+
+### Data
+- `data:list`: pretty JSON response.
+- `data:get`: pretty JSON response.
+- `data:create`: pretty JSON response.
+- `data:update`: pretty JSON response.
+- `data:delete`: pretty JSON response.
+- `data:export`: writes JSON file + summary line.
+  - `--json`: `{ success, collection_id, project_id, count, output }`
+- `data:import`:
+  - default: summary (`created`, `updated`)
+  - `--dry-run`: simulated summary lines
+  - `--json`: structured import result (`success`, `collection_id`, `project_id`, `mode`, `batch`, `dryRun`, `created`, `updated`, `match?`)
+
+### Revision/Alias Definition (Important)
+- Function revision is system-managed and immutable (`r1`, `r2`, ...).
+- You cannot set custom revision id (for example git hash) as revision.
+- If you need git-traceable deployment labels, use alias names as git hash values.
+- Example:
+  - `function:alias:set process-order a1b2c3d4 r42`
+  - `function:revisions process-order` (to inspect mapping + checksum)
 
 ## Development