@stackable-labs/cli-app-extension 1.36.2 → 1.37.0

package/README.md

@@ -5,13 +5,13 @@ CLI for scaffolding new [Stackable](https://www.npmjs.com/package/@stackable-lab
 ## Quick Start
 
 ```bash
-npx @stackable-labs/cli-app-extension@latest create my-extension
+pnpm --config.dlx-cache-max-age=0 dlx @stackable-labs/cli-app-extension@latest create my-extension
 ```
 
 Or run interactively with no arguments:
 
 ```bash
-npx @stackable-labs/cli-app-extension@latest create
+pnpm --config.dlx-cache-max-age=0 dlx @stackable-labs/cli-app-extension@latest create
 ```
 
 > **Important:** Always include `@latest` to ensure you get the most recent version. Both `npx` and `pnpm dlx` aggressively cache packages.
@@ -31,18 +31,80 @@ When run without all required flags, the CLI guides you through a step-by-step p
 | 7 | **Directory** | Output directory path (default: kebab-case of name) |
 | 8 | **Confirm** | Review all selections (including template) before scaffolding |
 
-## CLI Flags
+## Commands
+
+### `create [name]`
+
+Create a new Extension project from a template.
 
 ```
-Usage: create-extension [name] [options]
+Usage: stackable-app-extension create [name] [options]
+
+Arguments:
+  name                         Extension project name (prompted if omitted)
 
 Options:
-  --template <flavor>        Template flavor: minimal, starter, kitchen-sink (skips template prompt)
-  --extension-port <port>    Extension dev server port (skips port prompt)
-  --preview-port <port>      Preview host dev server port (skips port prompt)
-  --skip-install             Skip package manager install after scaffolding
-  --skip-git                 Skip git initialization
-  -h, --help                 Display help
+  --app-id <id>                Skip App selection
+  --project-id <id>            Studio project ID (fetches files/manifest from Studio)
+  --template <flavor>          Template flavor: minimal, starter, kitchen-sink
+  --extension-port <port>      Extension dev server port (default: 6543)
+  --preview-port <port>        Preview dev server port
+  --skip-install               Skip package manager install
+  --skip-git                   Skip git initialization
+```
+
+### `scaffold [extensionId]`
+
+Scaffold a local project from an existing Extension registered in the platform.
+
+```
+Usage: stackable-app-extension scaffold [extensionId] [options]
+
+Arguments:
+  extensionId                  Extension ID to scaffold from (prompted if omitted)
+
+Options:
+  --app-id <id>                App ID (auto-resolved from extensionId if omitted)
+  --project-id <id>            Studio project ID (fetches files/manifest from Studio)
+  --template <flavor>          Template flavor: minimal, starter, kitchen-sink
+  --extension-port <port>      Extension dev server port (default: 6543)
+  --preview-port <port>        Preview dev server port
+  --skip-install               Skip package manager install
+  --skip-git                   Skip git initialization
+```
+
+When `extensionId` is provided without `--app-id`, the CLI automatically resolves which App owns the extension by checking all your registered apps. When scaffolding a newly created extension (no existing local project), the template picker is shown unless `--template` or `--project-id` is provided.
+
+### `update [extensionId]`
+
+Update an existing Extension's metadata (name, targets, bundle URL, version, enabled state).
+
+```
+Usage: stackable-app-extension update [extensionId] [options]
+
+Arguments:
+  extensionId                  Extension ID to update (prompted if omitted)
+
+Options:
+  --app-id <id>                App ID (auto-resolved from extensionId if omitted)
+  --name <name>                New Extension name
+  --targets <targets>          Comma-separated target slots (validated against app)
+  --bundle-url <url>           New bundle URL
+  --enabled <bool>             Enable/disable Extension
+  --set-version <version>      Explicit version (skips auto-compute)
+  --dir <path>                 Project root (default: cwd)
+```
+
+When `extensionId` is provided without `--app-id`, the CLI automatically resolves which App owns the extension by checking all your registered apps. If `--app-id` is also provided, it takes precedence.
+
+### `auth`
+
+Manage CLI authentication.
+
+```
+stackable-app-extension auth login    # Authenticate via browser
+stackable-app-extension auth logout   # Clear stored credentials
+stackable-app-extension auth status   # Show current auth status
 ```
 
 ## Local Development
@@ -147,10 +209,7 @@ Both `npx` and `pnpm dlx` cache downloaded packages. If you're seeing an older v
 
 **npx** — Always use `@latest` and clear the cache if needed:
 ```bash
-npx @stackable-labs/cli-app-extension@latest create
-
-# If still stale, clear the npx cache:
-npx clear-npx-cache
+pnpm --config.dlx-cache-max-age=0 dlx @stackable-labs/cli-app-extension@latest create
 ```
 
 **pnpm dlx** — Bypass the 24-hour dlx cache: