Cloud CLI documentation (#2086)

* Write 1st draft of Cloud CLI + Update TOC * Improve and complete Cloud CLI documentation * Create file + Write guide for deploying projects with CLI * Update deploy introduction + project deploy guide for Cloud dashboard * Update TOC * Update TOC + Comment some paragraphs that may not be included in final version * Improve wording * Update wording for "hosted on remote git repo" Co-authored-by: Pierre Wizla <[email protected]> * Improve wording again for "hosted on remote git repo" Co-authored-by: Pierre Wizla <[email protected]> * Improve wording again Co-authored-by: Pierre Wizla <[email protected]> * Update docusaurus/docs/cloud/cli/cloud-cli.md Co-authored-by: Pierre Wizla <[email protected]> * Keep improving wording Co-authored-by: Pierre Wizla <[email protected]> * Remove unnecessary comments * Update docs after blitz session test * Improve after review * Add link to Dev Docs + Fix wording * Quick Start Guide and CLI installation guide updates for the Cloud CLI (#2119) * Update the Quick Start Guide to reflect new Cloud CLI behavior * Update the CLI installation docs * Add cross-link to QSG to CLI install. guide * Update docusaurus/docs/dev-docs/quick-start.md * Update docusaurus/docs/dev-docs/quick-start.md * Update docusaurus/docs/dev-docs/quick-start.md * Update docusaurus/docs/dev-docs/quick-start.md * Update docusaurus/docs/dev-docs/installation/cli.md Co-authored-by: Ben Irvin <[email protected]> * Update docusaurus/docs/dev-docs/installation/cli.md Co-authored-by: Ben Irvin <[email protected]> * Update docusaurus/docs/dev-docs/quick-start.md Co-authored-by: Ben Irvin <[email protected]> * Update docusaurus/docs/dev-docs/quick-start.md Co-authored-by: Ben Irvin <[email protected]> * Update docusaurus/docs/dev-docs/installation/cli.md * Update docusaurus/docs/dev-docs/installation/cli.md * Update docusaurus/docs/dev-docs/installation/cli.md * Update docusaurus/docs/dev-docs/installation/cli.md * Update docusaurus/docs/dev-docs/installation/cli.md * Update docusaurus/docs/dev-docs/installation/cli.md * Update docusaurus/docs/dev-docs/installation/cli.md * Update docusaurus/docs/dev-docs/quick-start.md * Swap NPM & Yarn tabs order * Shorten text --------- Co-authored-by: Ben Irvin <[email protected]> * Add "Updated" badge to QSG in TOC * Update completion time in QSG --------- Co-authored-by: Pierre Wizla <[email protected]> Co-authored-by: Ben Irvin <[email protected]> Co-authored-by: Pierre Wizla <[email protected]>
strapi · Jun 12, 2024 · b90c8ac · b90c8ac
1 parent 4d396b0
commit b90c8ac
Show file tree

Hide file tree

Showing 10 changed files with 336 additions and 90 deletions.
diff --git a/docusaurus/docs/cloud/cli/cloud-cli.md b/docusaurus/docs/cloud/cli/cloud-cli.md
@@ -0,0 +1,67 @@
+---
+sidebar_label: 'Cloud CLI'
+displayed_sidebar: cloudSidebar
+sidebar_position: 3
+---
+
+# Command Line Interface (CLI)
+
+Strapi Cloud comes with a Command Line Interface (CLI) which allows you to log in and out, and to deploy a local project without it having to be hosted on a remote git repository. The CLI works with both the `yarn` and `npm` package managers.
+
+The Cloud CLI is designed as a CLI-only experience, meaning that users who wish to use Strapi Cloud to deploy their project with the CLI will have to mostly stick to using the CLI (e.g. if you login with the CLI you must logout with the CLI as well, your project deployed with the CLI can only be redeployed with the CLI etc.).
+
+:::note
+It is recommended to install Strapi locally only, which requires prefixing all of the following `strapi` commands with the package manager used for the project setup (e.g `npm run strapi help` or `yarn strapi help`) or a dedicated node package executor (e.g. `npx strapi help`).
+:::
+
+## strapi login
+
+**Alias:** `strapi cloud:login`
+
+Log in Strapi Cloud.
+
+```bash
+strapi login
+```
+
+This command automatically opens a browser window to first ask you to confirm that the codes displayed in both the browser window and the terminal are the same. Then you will be able to log into Strapi Cloud via Google, GitHub or GitLab. Once the browser window confirms successful login, it can be safely closed.
+
+If the browser window doesn't automatically open, the terminal will display a clickable link as well as the code to enter manually.
+
+## strapi deploy
+
+**Alias:** `strapi cloud:deploy`
+
+Deploy a new local project (< 100MB) in Strapi Cloud.
+
+```bash
+strapi deploy
+```
+
+This command must be used after the `login` one. It deploys a local Strapi project on Strapi Cloud, without having to host it on a remote git repository beforehand. The terminal will inform you when the project is successfully deployed on Strapi Cloud.
+
+Once the project is first deployed on Strapi Cloud with the CLI, the `deploy` command can be reused to trigger a new deployment of the same project.
+
+:::caution
+The `deploy` command can only be used by new users who have never created a Strapi Cloud project, and for which the free trial is still available. Once a project is deployed with the CLI, it isn't possible to deploy another project on the same Strapi Cloud account with the CLI.
+:::
+
+:::note
+Once you deployed your project, if you visit the Strapi Cloud dashboard, you may see some limitations as well as impacts due to creating a Strapi Cloud project that is not in a remote repository and which was deployed with the CLI.
+
+- Some areas in the dashboard that are usually reserved to display information about the git provider will be blank.
+- Some buttons, such as the **Trigger deploy** button, will be greyed out and unclickable since you can only redeploy your project using the CLI.
+- Options such as environment variables, and features like the logs, are not available for CLI-created projects. <!-- to be confirmed -->
+:::
+
+## strapi logout
+
+**Alias:** `strapi cloud:logout`
+
+Log out of Strapi Cloud.
+
+```bash
+strapi logout
+```
+
+This command logs you out of Strapi Cloud. Once the `logout` command is run, the terminal will display a confirmation message that you were successfully logged out, and you will not be able to use the `deploy` command anymore.
diff --git a/docusaurus/docs/cloud/getting-started/deployment-cli.md b/docusaurus/docs/cloud/getting-started/deployment-cli.md
@@ -0,0 +1,80 @@
+---
+title: with Cloud CLI
+displayed_sidebar: cloudSidebar
+description: Learn how to deploy your Strapi application via the CLI.
+canonicalUrl: https://docs.strapi.io/cloud/getting-started/deployment-cli.html
+sidebar_position: 2
+---
+
+# Project deployment with the Command Line Interface (CLI)
+
+This is a step-by-step guide for deploying your project on Strapi Cloud for the first time, using the Command Line Interface.
+
+:::prerequisites
+Before you can deploy your Strapi application on Strapi Cloud using the Command Line Interface, you need to have the following prerequisites:
+
+- Be a first-time Strapi Cloud user: you must never have deployed a project with Strapi Cloud before, and your free trial must still be available.
+- Have a Google, GitHub or GitLab account.
+- Have an already created Strapi project (see [Installing from CLI in the Developer Documentation](/dev-docs/installation/cli)), stored locally. The project must be less than 100MB.
+- Have available storage in your hard drive where the temporary folder of your operating system is stored.
+:::
+
+## Logging in to Strapi Cloud
+
+1. Open your terminal.
+
+2. Navigate to the folder of your Strapi project, stored locally on your computer.
+
+3. Enter the following command to log into Strapi Cloud:
+
+<Tabs groupId="yarn-npm">
+<TabItem value="yarn" label="Yarn">
+
+```bash
+yarn strapi login
+```
+
+</TabItem>
+<TabItem value="npm" label="NPM">
+
+```bash
+npx run strapi login
+```
+
+</TabItem>
+</Tabs>
+
+4. In the browser window that opens automatically, confirm that the code displayed is the same as the one written in the terminal message.
+
+5. Still in the browser window, choose whether to login via Google, GitHub or GitLab. The window should confirm the successful login soon after.
+
+## Deploying your project
+
+1. From your terminal, still from the folder of your Strapi project, enter the following command to deploy the project:
+
+<Tabs groupId="yarn-npm">
+<TabItem value="yarn" label="Yarn">
+
+```bash
+yarn strapi deploy
+```
+
+</TabItem>
+<TabItem value="npm" label="NPM">
+
+```bash
+npx run strapi deploy
+```
+
+</TabItem>
+</Tabs>
+
+2. Follow the progression bar in the terminal until confirmation that the project was successfully deployed with Strapi Cloud.
+
+## ⏩ What to do next?
+
+Now that you have deployed your project via the Command Line Interface, we encourage you to explore the following ideas to have an even more complete Strapi Cloud experience:
+
+- Fill in your [billing information](/cloud/account/account-billing) to prevent your project from being suspended at the end of the trial period.
+- Visit the Cloud dashboard to follow [insightful metrics and information](/cloud/projects/overview) on your Strapi project.
+- Check out the full [Command Line Interface documentation](/cloud/cli/cloud-cli) to learn about the other commands available.
diff --git a/docusaurus/docs/cloud/getting-started/deployment-options.md b/docusaurus/docs/cloud/getting-started/deployment-options.md
@@ -0,0 +1,21 @@
+---
+title: Project deployment
+displayed_sidebar: cloudSidebar
+description: Learn how to deploy your Strapi application on Strapi Cloud, via the Cloud dashboard or the CLI.
+canonicalUrl: https://docs.strapi.io/cloud/getting-started/deployment-options.html
+sidebar_position: 2
+---
+
+# Project deployment with Strapi Cloud
+
+You have 2 options to deploy your project with Strapi Cloud:
+
+- either with the user interface (UI), meaning that you will perform all the actions directly on the Strapi Cloud dashboard,
+- or using the Cloud Comment Line Interface (CLI), meaning that you will only interact with a terminal.
+
+The guides below will guide you through all the steps for each of the deployment options. 
+
+<CustomDocCardsWrapper>
+  <CustomDocCard emoji="🖼️" title="Via the Cloud dashboard" description="Step-by-step guide to create and deploy a project via the user interface." link="/cloud/getting-started/deployment" />
+  <CustomDocCard emoji="💻" title="Via the CLI" description="Step-by-step guide to create and deploy a project with the Cloud Command Line Interface." link="/cloud/getting-started/deployment-cli" />
+</CustomDocCardsWrapper>
diff --git a/docusaurus/docs/cloud/getting-started/deployment.md b/docusaurus/docs/cloud/getting-started/deployment.md
@@ -1,17 +1,17 @@
 ---
-title: Project creation
+title: with Cloud dashboard
 displayed_sidebar: cloudSidebar
 description: Learn how to deploy your Strapi application on Strapi Cloud.
 canonicalUrl: https://docs.strapi.io/cloud/getting-started/deployment.html
 sidebar_position: 2
 ---
 
-# Project creation & deployment
+# Project deployment with the Cloud dashboard
 
-This is a step-by-step guide for creating and deploying your first project on Strapi Cloud.
+This is a step-by-step guide for deploying your project on Strapi Cloud for the first time, using the Cloud dashboard.
 
 :::prerequisites
-Before you can deploy your Strapi application on Strapi Cloud, you need to have the following prerequisites:
+Before you can deploy your Strapi application on Strapi Cloud using the Cloud dashboard, you need to have the following prerequisites:
 
 * Strapi version `4.8.2` or higher
 * Project database must be compatible with PostgreSQL. Strapi does not support and does not recommend using any external databases, though it's possible to configure one (see [advanced database configuration](/cloud/advanced/database)).
@@ -33,7 +33,7 @@ Before you can deploy your Strapi application on Strapi Cloud, you need to have
     }}
     />
 
-## Creating a project
+## Deploying a project
 
 1. From the *Projects* page, click the **Create project** button.
 
@@ -45,7 +45,7 @@ Before you can deploy your Strapi application on Strapi Cloud, you need to have
     }}
     />
 
-2. You will be redirected to the first project creation interface. This interface contains 3 steps: choosing a plan, connecting a git repository, and setting up the project.
+2. You will be redirected to the first project deployment interface. This interface contains 3 steps: choosing a plan, connecting a remote git repository, and setting up the project.
 
     <ThemedImage
     alt="Strapi Cloud project creation, step 1"
@@ -58,12 +58,12 @@ Before you can deploy your Strapi application on Strapi Cloud, you need to have
 3. Choose a plan for your Strapi Cloud project: either Developer, Pro, Team, or the 14-days free trial. Feel free to refer to [Pricing](https://strapi.io/pricing-cloud) for more information.
 
     :::note
-    Strapi Cloud offers a free trial for only one project and you will not need to share your credit card details to create your first project. Once the free trial has already been used for a previous project, the option will no longer appear in the plan selection.
+    Strapi Cloud offers a free trial for only one project and you will not need to share your credit card details to deploy your first project. Once the free trial has already been used for a previous project, the option will no longer appear in the plan selection.
     :::
 
 4. Connect a git repository to your new Strapi Cloud project.
 
-    :::strapi Choose your path to create your new Strapi Cloud project!
+    :::strapi Choose your path for your new Strapi Cloud project!
     Select one of the tabs below depending on how you wish to proceed:
     - by using a prebuilt template and creating a new repository on GitHub to discover Strapi Cloud easily and quickly *(recommended for new users and beginners — not available on another provider than GitHub)*,
     - or by using your own, already existing GitHub or GitLab repository and Strapi project.
@@ -73,7 +73,7 @@ Before you can deploy your Strapi application on Strapi Cloud, you need to have
 
     <TabItem value="TEMPLATE" label="New repo & prebuilt template ✨">
 
-    4.a. Click on the **Use template** button. If you are creating a project for the first time, you may first have to select GitHub as git provider and then you will see the option to use a template. 
+    4.a. Click on the **Use template** button. If you are deploying a project for the first time, you may first have to select GitHub as git provider and then you will see the option to use a template. 
 
     4.b. In the *Create repository with template* modal, choose:
 
@@ -93,7 +93,7 @@ Before you can deploy your Strapi application on Strapi Cloud, you need to have
 
     4.d. If you have already given Strapi Cloud access to all repositories of your GitHub account, go directly to the next step. If not, you will be redirected to a GitHub modal where you will have to allow Strapi Cloud access to the newly created repository (more information in the [GitHub documentation](https://docs.github.com/en/apps/overview)).
 
-    4.e. Back in the project creation interface, select your *Account* and the *Repository* you just created.
+    4.e. Back in the project deployment interface, select your *Account* and the *Repository* you just created.
 
     <ThemedImage
     alt="Selecting GitHub account and repository"
@@ -107,15 +107,15 @@ Before you can deploy your Strapi application on Strapi Cloud, you need to have
 
     <TabItem value="OWN-REPO" label="Own existing repo & Strapi project">
 
-    4.a. (optional) If you are creating a project for the first time, you may first have to select a git provider: either GitHub or GitLab. If you already created a project with one git provider, you can afterward create another project using another provider by clicking on the **Switch git provider** button and selecting either GitHub or GitLab.
+    4.a. (optional) If you are deploying a project for the first time, you may first have to select a git provider: either GitHub or GitLab. If you already deployed a project with one git provider, you can afterward deploy another project using another provider by clicking on the **Switch git provider** button and selecting either GitHub or GitLab.
 
     :::tip
     Connect the GitHub or GitLab account and/or organizations that own the repository or repositories you want to deploy. This can be different from the account that owns the Strapi Cloud account.
     :::
 
     4.b. If you have already given Strapi Cloud access to all repositories of your GitHub or GitLab account, go directly to the next step. If not, you will be redirected to a modal where you will have to allow Strapi Cloud permission to access some or all your repositories on GitHub/GitLab (more information in the [GitHub](https://docs.github.com/en/apps/overview) and [GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html#view-all-authorized-applications) documentations).
 
-    4.c. Back in the project creation interface, select your *Account* and a *Repository*. 
+    4.c. Back in the project deployment interface, select your *Account* and a *Repository*. 
 
     <ThemedImage
     alt="Selecting git account and repository"
@@ -176,7 +176,7 @@ During the free trial, will be kept informed of the number of remaining free day
 👉 Skip to step 5 of the section below to finalise the creation of your project.
 :::
 
-1. Click on the **Continue to billing** button. You will directly be redirected to the second and final project creation interface. There you can review all your new project setup information, enter payment & billing details and receive your invoice.
+1. Click on the **Continue to billing** button. You will directly be redirected to the second and final project deployment interface. There you can review all your new project setup information, enter payment & billing details and receive your invoice.
 
     <ThemedImage
     alt="Payment & Billing"
@@ -192,8 +192,16 @@ During the free trial, will be kept informed of the number of remaining free day
 
 4. Check your invoice which informs you of what should be paid now and the following month. Optionally, you can enter a *Discount code* if you have one.
 
-5. Click on the **Create project** button to finalize the creation of your new Strapi Cloud project. An initial deployment will automatically be triggered and you will be redirected to the *Projects* page.
+5. Click on the **Create project** button to finalize the deployment of your new Strapi Cloud project. An initial deployment will automatically be triggered and you will be redirected to the *Projects* page.
 
 :::caution
 Create your Admin user after the initial deployment is complete. Do not share your application URL with anyone until you have created your Admin user.
 :::
+
+## ⏩ What to do next?
+
+Now that you have deployed your project via the Cloud dashboard, we encourage you to explore the following ideas to have an even more complete Strapi Cloud experience:
+
+- If you chose the free trial during your first project deployment, make sure to fill in your [billing information](/cloud/account/account-billing) afterward to prevent your project from being suspended at the end of the trial period.
+- Invite other users to [collaborate on your project](/cloud/projects/collaboration).
+- Check out the [deployments management documentation](/cloud/projects/deploys) to learn how to trigger new deployments for your project.
diff --git a/docusaurus/docs/dev-docs/installation/cli.md b/docusaurus/docs/dev-docs/installation/cli.md
@@ -79,6 +79,8 @@ The above installation guide only covers the basic installation option using the
 - `--typescript`/`--ts`: Create a project in [TypeScript](/dev-docs/typescript).
 - `--no-run`: Prevent Strapi from automatically starting the server (useful in combination with `--quickstart`).
 
+- `--skip-cloud`: Automatically answers "Skip" to the Login/Signup question, which prevents the installation script from login into Strapi Cloud (useful in combination with `--quickstart`).
+
 For more information on available flags, see our [CLI documentation](/dev-docs/cli).
 
 Strapi also offers a starters CLI to create a project with a pre-made frontend application (see [our dedicated blog post](https://strapi.io/blog/announcing-the-strapi-starter-cli)).
@@ -89,6 +91,36 @@ Experimental Strapi versions are released every Tuesday through Saturday at midn
 Please use these experimental builds at your own risk. It is not recommended to use them in production.
 :::
 
+### Skipping the Strapi Cloud login step
+
+When the installation script runs, the terminal will first ask you if you want to login/signup. Choosing `Login/signup` will create a free, 14-day trial [Strapi Cloud](/cloud/intro#what-is-strapi-cloud) project as described in the [Quick Start Guide](/dev-docs/quick-start).
+
+If you prefer skipping this Strapi Cloud login part, use the arrow keys to select `Skip`. The script will resume and create a local project. To deploy this project and host it online, you could later choose to:
+- host it yourself by pushing the project's code to a repository (e.g., on GitHub) before following a [3rd-party deployment guide](/dev-docs/deployment),
+- or use the [Cloud CLI](/cloud/cli/cloud-cli) commands to login to Strapi Cloud and deploy your project there.
+
+If you want to host your project yourself and are not already familiar with GitHub, the following togglable content should get you started👇.
+
+<details>
+<summary>Steps required to push your Strapi project code to GitHub:</summary>
+
+1. In the terminal, ensure you are still in the folder that hosts the Strapi project you created.
+2. Run the `git init` command to initialize git for this folder.
+3. Run the `git add .` command to add all modified files to the git index.
+4. Run the `git commit -m "Initial commit"` command to create a commit with all the added changes.
+5. Log in to your GitHub account and [create a new repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/quickstart-for-repositories). Give the new repository a name, for instance `my-first-strapi-project`, and remember this name.
+6. Go back to the terminal and push your local repository to GitHub:
+
+  a. Run a command similar to the following: `git remote add origin [email protected]:yourname/my-first-strapi-project.git`, ensuring you replace `yourname` by your own GitHub profile name, and `my-first-strapi-project` by the actual name you used at step 4.
+
+  b. Run the `git push --set-upstream origin main` command to finally push the commit to your GitHub repository.
+
+Additional information about using git with the command line interface can be found in the [official GitHub documentation](https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#adding-a-local-repository-to-github-using-git).
+
+</details>
+
+
+
 ## Running Strapi
 
 To start the Strapi application, run the following command in the project folder: