@fluid-app/fluid-cli-portal 0.1.26 → 0.1.28

package/README.md

@@ -0,0 +1,107 @@
+# Fluid Portal CLI — Pull & Push App Manifests
+
+The Fluid CLI lets you pull a Fluid OS definition (your app manifest — screens, themes, navigations, profiles) into local JSON files, edit them, and push them back to production.
+
+## One-time setup
+
+- **Build the CLI** (from the repo root):
+
+  ```bash
+  pnpm --filter @fluid-app/fluid-cli --filter @fluid-app/fluid-cli-portal build
+  ```
+
+- The `fluid` binary is then at `packages/cli/core/dist/bin/fluid.mjs`. Optionally alias it:
+
+  ```bash
+  alias fluid="node /path/to/repo/packages/cli/core/dist/bin/fluid.mjs"
+  ```
+
+  (All examples below assume this alias. Without it, replace `fluid` with `node packages/cli/core/dist/bin/fluid.mjs`.)
+
+## Authenticate
+
+- **Email + MFA flow:**
+
+  ```bash
+  fluid login
+  ```
+
+- **Or skip MFA with an API token:**
+
+  ```bash
+  FLUID_TOKEN="<your-api-token>" fluid login
+  ```
+
+## Pull a definition
+
+```bash
+fluid portal pull
+```
+
+- Interactive picker, or target one directly: `fluid portal pull --app "<definition name>"`
+- Writes `portal/` (`screens/`, `themes/`, `navigations/`, `profiles/`, `definition.json`) plus a `.portal-sync/` folder that tracks sync state.
+- Switching to a different definition with unpushed local changes? Add `--force` to overwrite.
+
+## Edit & preview
+
+- Edit the JSON files under `portal/`.
+- Preview locally (serves the manifest from your local files):
+
+  ```bash
+  fluid portal dev
+  ```
+
+## Push changes back
+
+```bash
+fluid portal push
+```
+
+- Shows a diff and asks for confirmation (add `--yes` to skip).
+- **Push does NOT publish** — it updates the definition's working/draft state. End users keep seeing the currently-active published version.
+
+## Publish portal versions (only when you want manifest changes live)
+
+```bash
+fluid portal version create --activate     # snapshot current state + make it live
+fluid portal version list                  # see all versions
+fluid portal version activate <version-id> # promote a specific version
+```
+
+## Publish widget runtime artifacts
+
+Portal widget packages are published separately from the hosted portal shell.
+The portal CLI only publishes company-owned portal widget packages:
+
+```bash
+fluid portal deploy
+```
+
+- Builds `defineWidgetPackage` runtime artifacts (`widget.js`, `manifest.json`,
+  CSS, source maps) into `.fluid/widget-dist` by default.
+- Publishes a **company-owned** portal widget package for Fluid OS usage.
+- Defaults to `--environment production` (an output/reporting label) and
+  `--out-dir .fluid/widget-dist`.
+- Add `--dry-run` to build and print the upload payload without creating an
+  upload session.
+- This publishes widget runtime artifacts only; it does **not** deploy the
+  hosted portal shell.
+
+For droplet-owned marketplace widget packages, use the dedicated widget CLI
+(`@fluid-app/fluid-cli-widget`) instead:
+
+```bash
+fluid widget create my-widget --droplet <uuid>
+fluid widget link --droplet <uuid>
+fluid widget publish
+```
+
+Droplets are managed outside the widget CLI and must already exist before you
+link or publish a droplet-owned widget package.
+
+## Handy commands
+
+- `fluid whoami` — show the active profile
+- `fluid switch` — switch between profiles
+- `fluid logout` — clear stored credentials
+- `fluid portal doctor` — diagnose portal project issues