Initial docs on the CLI. (#248)

website/docs/cli/commands/poc.md

@@ -0,0 +1,41 @@
+---
+title: CLI Command - poc
+sidebar_label: poc
+---
+
+One common scenario during the Portals development lifecycle is that a Portal has been defined in the Native
+application but there is not yet a web application available to test against it. This command
+is meant resolve this scenario and allow native developers to have confidence in how the Portal
+was configured.
+
+The `poc` command will download a prebuilt example application to a predefined directory. The portal
+can then be configured to point to this application for testing purposes. The web application reflects
+the `initialContext` and plugins that have been exposed. You can also even use the web application to
+test some pub/sub interactions.
+
+### Usage:
+
+```bash
+portals poc [flags]
+```
+
+### Aliases:
+
+```bash
+poc, sample-app
+```
+
+### Examples:
+
+```bash
+portals poc [--destination path/to/copy/web/apps]
+```
+
+### Flags:
+
+- `--destination` **(string)** The location to download the web application to.
+- `-h, --help` help for sync
+
+### Global Flags:
+
+- `--config` **(string)** config file (default is $PWD/.portals.yaml)

website/docs/cli/commands/sync.md

@@ -0,0 +1,37 @@
+---
+title: CLI Command - sync
+sidebar_label: sync
+---
+
+During the build process of Native Applications it is good practice to pull the latest Live Updates available
+from each of the web applications that are used in the Portals. This ensures that the native release is shipping
+with the latest web applications instead of relying on a live update to immediately update.
+
+The `sync` CLI command will query the Live Update service, download, and extract the latest builds for a set of configured Appflow Applications.
+
+When running inside of an Xcode Run Script build step the destination will default to
+the root of the built target: `$BUILT_PRODUCTS_DIR/$TARGET_NAME.app`
+
+When running under any other context the destination will default to the current working
+directory.
+
+### Usage:
+
+```bash
+portals sync [flags]
+```
+
+### Examples:
+
+```bash
+portals sync [--destination path/to/copy/web/apps]
+```
+
+### Flags:
+
+- `--destination` **(string)** The location to download the web applications to.
+- `-h, --help` help for sync
+
+### Global Flags:
+
+- `--config` **(string)** config file (default is $PWD/.portals.yaml)

website/docs/cli/configuration.md

@@ -0,0 +1,103 @@
+---
+title: Portals CLI Configuration
+sidebar_label: Configuration
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+The Portals Configuration file allows you to specify configuration details for syncing multiple Portals applications. This file is used to define the apps to be synchronized and various settings related to those apps. Before you begin you will need a Personal Access Token.
+
+### Create a Personal Access Token
+
+Now that we have the web application all setup in Appflow and built we need to get our local environment setup to be able to pull it from Appflow.
+
+The first step in setting up our local environment is [generating a personal access token](https://dashboard.ionicframework.com/settings/personal-access-tokens).
+
+This is done from `Personal Settings` in the `Personal Access Token` tab.
+
+<em style={{
+  textAlign: 'center',
+  display: 'block'
+}}>
+<img src={useBaseUrl("/img/personal-access-token-thumbnail.webp")} data-zoom-src={useBaseUrl("/img/personal-access-token.webp")} width="75%"/>
+</em>
+
+Click the `Generate new token` button. While creating the token it is a best practice to give it an optional expiration date but not required.
+
+:::tip
+After the token is generated you will need to copy it to clipboard because it will be required for the next step. Usually the token follows the format of `ion_XXXXXXXXXXXXX`.
+:::
+
+# Portals CLI Configuration
+
+Below is the schema and documentation for the configuration options:
+
+```yaml
+sync:
+  - app-id: [PORTALS_APP_ID]
+    channel: [CHANNEL]
+    directory-name: [DIRECTORY_NAME]
+  - app-id: [PORTALS_APP_ID]
+    channel: [CHANNEL]
+    directory-name: [DIRECTORY_NAME]
+  # ... (add more apps if needed)
+
+token: [PORTALS_AUTH_TOKEN]
+```
+
+### Configuration Options
+
+1. **`sync` (List of Apps)**
+
+   - This is a list of apps that you want to synchronize. Each app is specified as a dictionary with the following attributes.
+
+   - **`app-id` (Required)**
+
+     - Type: String
+     - Description: The unique identifier for the Appflow application you want to sync.
+
+   - **`channel` (Optional)**
+
+     - Type: String
+     - Default: `production`
+     - Description: The channel of the Appflow application to be synchronized.
+
+   - **`directory-name` (Optional)**
+     - Type: String
+     - Default: the `app-id` will be used
+     - Description: The directory name where the synchronized app will be saved.
+
+2. **`token` (Required)**
+   - Type: String
+   - Description: The authentication token required to access Portals and perform sync operations. This token should be kept secure, as it provides access to your Appflow deployments.
+
+### Usage
+
+1. **`sync` Section**
+
+   - Add entries under the `sync` section to define the Portals applications you want to synchronize.
+   - Specify the `app-id` for each application to identify it.
+   - Optionally, provide a `channel` to specify a specific version or branch of the app to sync.
+   - Optionally, define a `directory-name` to specify the directory where the synchronized app will be saved.
+
+   Example:
+
+   ```yaml
+   sync:
+     - app-id: 186b544f
+     - app-id: a7b10ac1
+       channel: development
+       directory-name: home
+     - app-id: a81b2440
+       directory-name: cart
+   ```
+
+2. **`token` Section**
+
+   - In the `token` section, provide your Appflow Personal Access Token.
+
+   Example:
+
+   ```yaml
+   token: ion_Bq2aIK8JeREJKLC8FDhWO84pHrvmvde4ceayS
+   ```

website/docs/cli/overview.md

@@ -0,0 +1,54 @@
+---
+title: CLI Overview
+sidebar_label: Overview
+---
+
+# Portals CLI
+
+The Portals CLI is a command-line tool designed to simplify and streamline the management and deployment of your Portals projects. It empowers developers to interact with Portals programmatically, automating common tasks and enhancing productivity. The CLI provides functionality for both Native Developers and Web Developers.
+
+The CLI is a companion tool but is not required to use Portals.
+
+## Installation
+
+Installing the Ionic Portals CLI is a straightforward process, with options available for macOS, Linux, Windows, and various distribution methods to suit your preferences. Here's how to get started on your platform of choice:
+
+### Homebrew
+
+If you're using macOS or Linux, you can streamline the installation process with Homebrew. First, tap into the Portals releases repository and then install Portals with these commands:
+
+```bash
+# tap the Portals releases repository
+brew tap ionic-team/portals https://github.com/ionic-team/portals-cli-releases.git
+
+# install
+brew install portals
+```
+
+### Shell script
+
+Another option for macOS and Linux users is the shell script-based installation. Execute this single command to install Portals:
+
+```bash
+curl -sL https://raw.githubusercontent.com/ionic-team/portals-cli-releases/main/install.sh | bash
+```
+
+### Windows Binaries
+
+For Windows users, manual installation is currently required. You can download the appropriate zip file for your architecture (arm64, i386, or x86_64) from the list provided and extract it to a directory on your system's `PATH` for convenient access.
+
+- [arm64](https://github.com/ionic-team/portals-cli-releases/releases/latest/downloads/portals_Windows_arm64.zip)
+- [i386](https://github.com/ionic-team/portals-cli-releases/releases/latest/downloads/portals_Windows_i386.zip)
+- [x86_64](https://github.com/ionic-team/portals-cli-releases/releases/latest/downloads/portals_Windows_x86_64.zip)
+
+### Linux Binaries
+
+Debs and RPMs are made available for each [release](https://github.com/ionic-team/portals-cli-releases/releases).
+Download the appropriate package for your system and install with your package manager.
+
+## Command List​
+
+View all available CLI commands and options.
+
+- [poc](./commands/poc.md)
+- [sync](./commands/sync.md)

website/sidebars.js

@@ -204,7 +204,6 @@ module.exports = {
     },
     {
       type: "category",
-      className: "bottom-item",
       label: "Portals Web Plugin",
       collapsed: true,
       items: [
@@ -218,6 +217,22 @@ module.exports = {
         "for-web/changelog",
       ],
     },
+    {
+      type: "category",
+      className: "bottom-item",
+      label: "Portals CLI",
+      collapsed: true,
+      items: [
+        "cli/overview",
+        "cli/configuration",
+        {
+          type: "category",
+          label: "Command Reference",
+          collapsed: true,
+          items: ["cli/commands/poc", "cli/commands/sync"],
+        },
+      ],
+    },
     {
       type: "category",
       label: "Federated Capacitor",