CLI for Launch

Launch is a deployment platform that enables you to host your Contentstack-powered JAM stack website instantly. Launch hosts websites managed by any CMS (headless or traditional).

You can create a new project in Launch and link it with your GitHub repository. Launch picks that code and deploys your website instantly. Launch also allows you to create a project by directly uploading a project folder or a .zip file.

This step-by-step guide discusses how you can perform different operations in Launch using the CLI.

Prerequisites

• Contentstack account
• CLI installed and configured for AWS (version 1.6.0 and above), Azure (version 1.23.0 and above), or GCP (version 1.31.0 and above)
• CLI authenticated
• Access to Launch for your organization
• GitHub account where your website code is hosted

  Note: This prerequisite is applicable only if you are importing a project via GitHub.

Commands

Contentstack Launch lets you perform the following operations in Contentstack CLI:

• Launch (Create a Project)
• Logs
• Functions
• Deployments
• Environments
• Open

Launch (Create a Project)

To begin with, create a project in Launch using the CLI by importing a project from GitHub or uploading a file. To do this, follow the steps given below:

1. Open the terminal and fire the launch command:
   • Run the below command if you are in the current working directory.
     csdx launch
     

   • If you are in a different directory, provide the path of the current working directory.
     csdx launch --data-dir <path>
     

     Note: If you choose GitHub to create your project, provide the directory path in the Git repository as the current working directory path.

   Note: Launch automatically identifies Git projects.

2. If your current working directory is not a Git repository, you will be prompted to choose a project type to proceed. Select Continue with GitHub or Continue with FileUpload to proceed.
   
3. Select the organization where you want to create your project.
4. In this step, select a branch if you decided to create your project using GitHub.
5. Enter a name for your project.
6. Enter a name for your Environment or press Enter to proceed with the Default environment.
7. By default, Launch identifies the framework. Select a Framework Preset if you want to change the default framework, and then press Enter.
8. In the Build Command section, perform one of the following:
   • Press Enter if you want to proceed with the default Build command npm run build.
   • Or, enter a new build command or update the existing command if you want to customize the command.
9. Enter the output path in the Output Directory section or press Enter to proceed with the default output path.
10. In the next step, follow the instructions provided on screen to perform one of the following:
    • Import variables from a stack
    • Manually add custom variables to the list
    • Import variables from the local env file

      Note: Create a .env.local file in the repo to import variables from the local env file.

11. A prompt, Would you like to add more variables.? appears.
    • Enter Y to add another custom variable.
    • Enter n to proceed with the project deployment.
    You have successfully deployed a Launch project using the CLI.

Usage

csdx launch

Options

• -a, --alias=alias_token: [optional] Alias (name) for the delivery token.
• -d, --data-dir=data-dir: Current working directory.
• -c, --config=config: Path to the local config file.
• --type=type: Type of adapters. <options: GitHub|FileUpload>
• -e, --environment=environment: [optional] Environment name for the Launch project.
• -n, --name=name: [optional] Name of the project.
• --branch=branch: [optional] GitHub branch name.
• --build-command=build-command: [optional] Build Command.
• --env-variables=env-variables: [optional] Provide the environment variables in the key:value format, separated by comma. For example: APP_ENV:prod, TEST_ENV:testVal
• --framework=<option>: [optional] Type of framework. <options: <Gatsby|NextJS|Other>
• --org=org: [optional] Provide the organization UID to create a new project or deployment.
• --out-dir=outdir: [optional] Output Directory.
• --init: [Optional, Hidden] Reinitialize the project if it is an existing Launch project.
• --variable-type=variable-type: [optional] Provide a variable type. <options: Import variables from a stack|Manually add custom variables to the list|Import variables from the local env file>

Examples

• To create a Launch project by providing the config file path and file type:
  csdx launch --config <path/to/launch/config/file> --type <options: GitHub|FileUpload>
  

• To create a Launch project by providing the directory path and file type:
  csdx launch --data-dir <path/of/current/working/dir> --type <options: GitHub|FileUpload>
  

• To create a Launch project by providing a variable type:
  csdx launch --config <path to launch config file> --type <options: GitHub|FileUpload> --name=<value> --environment=<value> --branch=<value> --build-command=<value> --framework=<option> --org=<value> --out-dir=<value> --variable-type="Import variables from a stack" --alias=<value>
  

• To create a Launch project by providing a variable type and environment variables:
  csdx launch --config <path to launch config file> --type <options: GitHub|FileUpload> --name=<value> --environment=<value> --branch=<value> --build-command=<value> --framework=<option> --org=<value> --out-dir=<value> --variable-type="Manually add custom variables to the list" --env-variables="APP_ENV:prod, TEST_ENV:testVal"
  

Note: If multiple branches are identified in the configuration, you will be prompted to Choose a branch to proceed with the Launch operations. A single config file can have multiple configurations based on the branch.

Launch (Redeploy an Existing Project)

To redeploy or re-initialize an existing project, run the launch command using the project’s directory path or execute it from the current working directory.

• If the cs-launch.json file is present in the project directory, the project will be redeployed with the latest code.
• If the cs-launch.json file is absent, you will be prompted to create a new project.

To redeploy using the project’s directory path, run the following command:

csdx launch --data-dir <project-directory-path>

To redeploy from the current working directory, run the following command:

csdx launch

After running the command, you will see a prompt to Redeploy latest commit/code? as shown in the screenshot below:

• Press Y to redeploy the project.
  If using the File Upload method, you will see the following prompt:
  Redeploy with last file upload?.
  • Press y to redeploy with the previously uploaded file.
  • Press N to redeploy by uploading a new file.

  Note: By default, the launch command assumes you want to redeploy with a new file.

• Press n to cancel the process.

Logs

You can fetch the previous deployment logs and the latest server logs for Launch projects in CLI using the launch:logs command.

1. Open a terminal and fire the launch:logs command:
   csdx launch:logs
   

2. Select the organization where you created the project.
3. Select your project for which you want to fetch the logs.
4. Select the required environment.
You have successfully fetched the logs for your selected project.

Usage

csdx launch:logs

Options

• -d, --data-dir=data-dir: Current working directory.
• -c, --config=config: Path to the local config file.
• -e, --environment=environment: Environment name or UID.
• --deployment=deployment: Deployment number or UID.
• --type=type: Type of flags to show logs. By default, these are server logs. Options [d - deployment logs, s - server logs]

Note: If you do not pass a deployment ID, by default Launch fetches the latest deployment logs.

Examples

• To fetch Launch project logs based on the environment number and type of flags:
  csdx launch:logs -e "environment number or uid" --type "types of flags"
  

• To fetch Launch project logs based on the environment number and deployment number:
  csdx launch:logs -e "environment number or uid" --deployment "deployment number or uid"
  

Functions

You can test your Launch project Cloud Functions locally using the launch:functions command in CLI.

Usage

csdx launch:functions

Options

• -d, --data-dir=data-dir: Current working directory.
• -c, --config=config: Path to the local config file.
• -p, --port=port: [default: 3000] Port number.

Examples

• To test your Launch project Cloud Function locally:
  csdx launch:functions
  

• To test your Launch project Cloud Function locally in a specific port:
  csdx launch:functions -p "port number"
  

Deployments

You can display the list of deployments for an environment for Launch projects using the launch:deployments command in CLI.

1. Open a terminal and fire the launch:deployments command:
   csdx launch:deployments
   

2. Select the organization where you created the project.
3. Select your project.
4. Select the environment for which you want to list the deployments.

You have successfully listed the deployments for the selected environment.

Usage

csdx launch:deployments

Options

• -d, --data-dir=data-dir: Current working directory.
• -c, --config=config: Path to the local '.cs-launch.json' file.
• -e, --environment=environment: Environment name or UID.
• -–org=org: [Optional] Provide the organization UID.
• -–project=project: [Optional] Provide the project UID.

Examples

• To list the deployments in your current working directory
  csdx launch:deployments -d "current working directory"
  

• To list the deployments for a given environment
  csdx launch:deployments -e "environment number or uid"
  

Environments

You can display the list of environments that are available for a particular project using the launch:environments command in CLI.

1. Open a terminal and fire the launch:environments command:
   csdx launch:environments
   

2. Select the organization where you created the project.
3. Select your project.

You have successfully listed the environments for the selected project.

Usage

csdx launch:environments

Options

• -d, --data-dir=data-dir: Current working directory.
• -c, --config=config: Path to the local '.cs-launch.json' file.
• -–org=org: [Optional] Provide the organization UID.
• -–project=project: [Optional] Provide the project UID.

Examples

• To list the environments in your current working directory
  csdx launch:environments -d "current working directory"
  

• To list the environments for a specific project under a given organization
  csdx launch:environments --org=<org UID> --project=<Project UID>
  

Open

You can open the live site for an environment of your Launch projects using the launch:open command in CLI.

1. Open the terminal and fire the launch:open command:
   csdx launch:open
   

2. Select the organization where you created the project.
3. Select your project.
4. Select the environment for which you want to view the live site.

You have successfully opened the live site for the selected environment.

Usage

csdx launch:open

Options

• -d, --data-dir=data-dir: Current working directory.
• -c, --config=config: Path to the local '.cs-launch.json' file.
• -e, --environment=environment: Environment name or UID.
• -–org=org: [Optional] Provide the organization UID.
• -–project=project: [Optional] Provide the project UID.

Examples

• To open the website for an environment by passing your current working directory
  csdx launch:open --environment=environment --data-dir <path/of/current/working/dir>
  

• To open the website for an environment for a given configuration
  csdx launch:open --environment=environment --config <path/to/launch/config/file>