@canva/cli 0.0.1-beta.3 → 0.0.1-beta.5

package/README.md

@@ -7,200 +7,270 @@ CLI for creating and managing Canva Apps.
 ## Table of contents
 
 - [Introduction](#introduction)
-- [Features](#features)
-- [Usage](#usage)
+- [Requirements](#requirements)
+- [Quickstart](#quickstart)
+- [Use the Canva CLI](#use-the-canva-cli)
+  - [Step 1: Install and log in](#step-1-install-and-log-in)
+  - [Step 2: Create your app](#step-2-create-your-app)
+  - [Step 3: Preview your app](#step-3-preview-your-app)
+- [Log out, auth token storage, and removal](#token-storage-and-removal)
 - [CLI reference](#cli-reference)
   - [Flags](#flags)
   - [Commands](#commands)
 - [Next steps](#next-steps)
 - [Limitations](#limitations)
-- [Updating](#updating)
-- [Contributing](#contributing)
+- [Updates](#updating)
+- [Contributions](#contributing)
 - [License](#license)
 
 ## Introduction
 
-`@canva/cli` is a command line tool designed for creating and managing Canva Apps. To learn more about app development, visit [the official documentation](https://www.canva.dev/docs/apps).
+`@canva/cli` is a command line tool designed for creating and managing Canva Apps. Use `@canva/cli` to get started creating and testing your app. The Canva CLI allows you to create apps from the command line, and to use Canva's recommended development tools and templates.
 
-## Features
+To learn more about app development, visit [the official documentation](https://www.canva.dev/docs/apps).
 
-- Log in to your Canva account.
-- Create and manage apps directly from the command line.
-- Utilize Canva's recommended development tools and templates.
+## Requirements
 
-## Prerequisites
+Before using the CLI, make sure that you have the following:
 
-Before using the CLI, ensure that you have the following installed:
+- Node.js `v18.20.4` or `v20.17.0`.
+- npm `v9` or `v10`.
+- A [Canva account](https://www.canva.com/developers).
 
-- Node.js `v18.20.4` or `v20.17.0`
-- npm `v9` or `v10`
+  **Note**: If you are using a version manager such as nvm, run the `nvm install 20.17.0` command to make sure you have the correct Node.js version.
 
-## Usage
+## Quickstart
 
-To start using the CLI, first install it globally:
+The following commands create a new Canva app using the Canva CLI.
 
-```bash
-npm install -g @canva/cli
+```shell
+npm install -g @canva/cli@latest
+canva login
+canva apps create "My New App" --template="hello_world" --distribution="public" --git --installDependencies
+cd my-new-app
+npm start
 ```
 
-After installation, you can use the CLI by running:
+## Use the Canva CLI
 
-```bash
-canva <command>
-```
+### Step 1: Install and log in
 
-## CLI Reference
+Installing the Canva CLI allows you to create new apps from the command line.
 
-### Flags
+To get started:
 
-Top-level flags applicable across commands:
+1. Install the Canva CLI globally.
 
-- `--help`: Display help information about commands and flags.
-- `--lite`: Enable a simplified CLI interface for enhanced accessibility.
-- `--version`: Show the version number of the CLI.
+   ```shell
+   npm install -g @canva/cli@latest
+   ```
 
-### Commands
+2. Log in to the Canva CLI. The Canva CLI then opens an access request page in your browser.
 
-#### welcome
+   ```shell
+   canva login
+   ```
 
-Display the welcome page and general information.
+3. In your browser, click **Allow** to grant the Canva CLI access to create and edit apps on your behalf. When you grant access, the Canva CLI generates an auth token and stores it locally. For more information on the auth token, read the following section on [auth token storage and removal](#log-out-auth-token-storage-and-removal).
+4. Copy the confirmation code shown in your browser, and paste it into the Canva CLI input.
 
-- **Usage**:
+### Step 2: Create your app
 
-  ```bash
-  canva welcome
-  ```
+After you log in to the Canva CLI and authorize it, you can create your app.
 
-#### tip
+To create a new app:
 
-Get a random development tip for working with the Apps SDK.
+1. Run the `canva apps create` command. The flags in the following code snippet are optional, and you can instead configure these settings during the apps creation process. See the [CLI Reference](#cli-reference) for more information on each flag.
 
-- **Usage**:
+   ```shell
+   canva apps create "My New App" --template="hello_world" --distribution="public" --git --installDependencies
+   ```
 
-  ```bash
-  canva tip
-  ```
+   **Note**: You can't change the distribution type after creating an app.
 
-- **Aliases**: `tips`
+### Step 3: Preview your app
 
-#### login
+When your new app is ready, the Canva CLI automatically opens the [Developer Portal](https://www.canva.com/developers/apps) to your new app's Configuration page in your browser. You can then continue to preview and manage your new app.
 
-Log in to the Canva CLI.
+To preview your app:
 
-- **Usage**:
+1. Change into your new app's folder.
 
-  ```bash
-  canva login
-  ```
+   ```shell
+   cd my-new-app
+   ```
 
-#### apps
+2. Run the following command to start your app.
 
-Manage your Canva apps.
+   ```shell
+   npm start
+   ```
 
-- **Usage**:
+3. In the Developer Portal, click **Preview** to open the Canva Editor preview.
+4. If this the first time previewing your app, click **Open** to preview your new app.
 
-  ```bash
-  canva apps
-  ```
+## Log out, auth token storage, and removal
+
+When you log in to the Canva CLI using the `canva login` command, and then grant the Canva CLI access to manage apps in your Canva account, an auth token is encrypted and stored locally on your machine. The token provides authentication for future requests so you don't need to grant the Canva CLI access each time it sends a request.
 
-- **Sub-Commands**:
+When you log out of the Canva CLI with the `canva logout` command, the auth token is revoked, and deleted.
 
-  - `create [name]`: Create a new Canva app.
+### Token Location
 
-    - **Usage**:
+The auth token is located in your home directory under the `.canva-cli` folder.
 
-      ```bash
-      canva apps create "My New App" --template="hello_world" --distribution="public" --git --installDependencies
-      ```
+### Removing the Token
 
-    - **Arguments**:
-      - `[name]`: Sets the app's name. Provide the desired name of the app when using this command.
-    - **Flags**:
+To delete the token, there are two options. However only the `canva logout` command revokes and deletes the token. If there's a copy of the token, it's possible to reconnect the Canva CLI to your account's apps using the token.
 
-      - `--template`: Specifies the starting template for the app.
+#### Log out
 
-        Available templates:
+1. Use the `canva logout` command to revoke access and delete the stored token.
 
-        - `"hello_world"`: Basic starting point.
-        - `"dam"`: Digital asset management integration.
-        - `"gen_ai"`: Generative AI app creation.
+   ```shell
+   canva logout
+   ```
 
-      - `--distribution`: Sets the app's distribution type.
+#### Delete the file manually
 
-        Options:
+1. Locate the `credentials` file, which is stored in the following locations:
 
-        - `"public"`: Available to all Canva users, subject to Canva review.
-        - `"private"`: Only available to your team, requires team admin approval.
+   - **macOS and Linux**: The token is stored in `~/.canva-cli/credentials`.
+   - **Windows**: The token is stored in `%USERPROFILE%\.canva-cli\credentials`.
 
-        > [!Note]
-        > This setting cannot be changed after the app is created.
+2. Delete the file.
 
-      - `--git`: Initializes a Git repository in the project directory.
+## CLI Reference
 
-      - `--installDependencies`: Automatically installs necessary npm dependencies.
+After installation, you can use the Canva CLI by running:
 
-  - `list`: List all Canva apps.
+```shell
+canva <command-name>
+```
 
-    - **Usage**:
+### Flags
+
+Top-level flags applicable to commands:
 
-      ```bash
-      canva apps list
-      ```
+- `--help`: Show help information about commands and flags.
+- `--lite`: Enable a simplified CLI interface for enhanced accessibility.
+- `--version`: Show the CLI version number.
+
+### Commands
+
+#### welcome
+
+Show the welcome page and general information.
+
+```shell
+canva welcome
+```
+
+#### tip
+
+Print a random development tip for working with the Apps SDK.
+
+```shell
+canva tip
+```
+
+- **Aliases**:
+  - `tips`: Also prints a random development tip.
+
+#### login
+
+Log in to the Canva CLI.
+
+```shell
+canva login
+```
 
 #### logout
 
-Log out and revoke access from the CLI.
+Log out of the Canva CLI, and delete the saved auth token:
 
-- **Usage**:
+```shell
+canva logout
+```
 
-  ```bash
-  canva logout
+#### apps
+
+Manage your Canva apps.
+
+```shell
+canva apps
+```
+
+#### apps sub-commands
+
+- `create "app-name"`: Create a new Canva app.
+
+  ```shell
+  canva apps create "My New App" --template="hello_world" --distribution="public" --git --installDependencies
   ```
 
-## Next Steps
+  - **Arguments**:
+    - `--name`: Sets the app's name. Provide the name you want for the app.
+  - **Flags**:
 
-- [Preview your app in the Canva editor](https://www.canva.dev/docs/apps/previewing-apps/)
-- [Integrate your app with Canva using the Apps SDK](https://www.canva.dev/docs/apps/integrating-canva/)
+    - `--template`: Specifies the starting template for the app.
 
-## Limitations
+      Available templates:
 
-Once an app is created, it must be managed through Canva's [Developer Portal](https://www.canva.com/developers/apps) and cannot be fully managed via the CLI.
+      - `"hello_world"`: Basic starting point.
+      - `"dam"`: Digital asset management integration.
+      - `"gen_ai"`: Generative AI app creation.
 
-## Updating
+    - `--distribution`: Sets the app's distribution type.
 
-To update the CLI to the latest version, run:
+      Available types:
 
-```bash
-npm update -g @canva/cli
-```
+      - `"public"`: Available to all Canva users, subject to Canva review.
+      - `"private"`: Only available to your team, and requires team admin approval.
 
-## Token Storage and Removal
+        **Note**: You can't change the distribution setting after creating a new app with the `canva apps create` command.
 
-When you log in using the `canva login` command, the Auth token is encrypted and stored locally on your machine. This token is used to authenticate future requests made by the CLI, so you don’t have to log in repeatedly.
+    - `--git`: Initializes a Git repository in the project directory.
 
-### Token Location
+    - `--installDependencies`: Automatically installs necessary npm dependencies during the app creation process.
 
-The token is stored in a credentials file located in your home directory under the `.canva-cli` folder:
+    - `--offline`: Scaffold the app locally without also creating an app in the Developer Portal.
 
-### Removing the Token
+- `list`: List all Canva apps.
+
+  ```shell
+  canva apps list
+  ```
 
-To remove the token and log out of the CLI, you can either:
+#### logout
 
-1. Use the `canva logout` command to revoke access and delete the stored token:
+Log out and revoke Canva CLI access.
 
-   ```bash
-   canva logout
-   ```
+```shell
+canva logout
+```
+
+## Next Steps
+
+- [Preview your app in the Canva editor](https://www.canva.dev/docs/apps/previewing-apps/)
+- [Integrate your app with Canva using the Apps SDK](https://www.canva.dev/docs/apps/integrating-canva/)
+
+## Limitations
+
+You must manage your new app created through the Canva CLI through the [Developer Portal](https://www.canva.com/developers/apps). You can't manage apps completely through the Canva CLI.
 
-2. Manually delete the credentials file:
+## Updates
 
-- **macOS/Linux**: The token is stored in `~/.canva-cli/credentials`.
-- **Windows**: The token is stored in `%USERPROFILE%\.canva-cli\credentials`.
+To update the CLI to the latest version, run:
+
+```shell
+npm update -g @canva/cli@latest
+```
 
-## Contributing
+## Contributions
 
-We're in active development and currently do not accept third-party contributions. Please submit any feature requests through the [Canva Developers Community](https://community.canva.dev/).
+Currently the Canva CLI doesn't accept third-party contributions. Please submit any feature requests through the [Canva Developers Community](https://community.canva.dev/).
 
 ## License
 
-Refer to the `LICENSE.md` file for licensing details.
+Refer to the `LICENSE.md` file for more information.