Introduction

Developer CLI is a command-line tool that helps you build and modify Text applications. It provides a set of commands that you can use to create, develop, and deploy your Text apps.

With the CLI, you can:

• Create a new Text app from scratch
• Bootstrap our repository and app templates, for example, Next.js SaaS template
• Add building blocks to your app without entering the Developer Console
• Update your app by editing its manifest (livechat.config.json)

Installation

Start by installing the newest version of the Developer CLI using either npm or yarn.

npm install -g @livechat/developer-cli

or

yarn global add @livechat/developer-cli

Modules

The CLI has two modules that you can use to manage your Text apps:

• auth - authorize to the CLI and external providers
• app - create and manage apps

💡 Run txdev --help to lists available modules and options.

App manifest

Each application in the Developer Console is represented by an app manifest (livechat.config.json). There are two ways to edit an application via CLI:

1. Run a command from the txdev app module.
   
   Running a command will automatically update your app in the Developer Console. After that, pull the changes to the app manifest (txdev app pull) as it doesn't update automatically.
   
   We recommend this method to apply more complex changes, such as adding an enitre building block.

2. Edit livechat.config.json manually.
   
   Then, run txdev app push to push the changes to the Developer Console.
   
   We recommend this method to apply small, quick changes, such as adding a new scope.

{
  "id": "BgYQO_BIg",
  "name": "EmptyApp",
  "product": "livechat",
  "blocks": {
    "authorization": {
      "clientId": "5c4d731184619046c915549fb09c1561",
      "type": "server_side_app",
      "redirectUri": "https://myapp.com,https://myapp.com/settings",
      "scopes": [
        {
          "scope": "archives_read",
          "required": true
        },
        {
          "scope": "chats.conversation--my:rw",
          "required": true
        }
      ]
    }
  }
}

Not every field can be modified, for example, you can't change the value of client_id.

Application context

Most CLI commands need to be run within the context of the application you're working on. The exceptions from this rule would be txdev app create, txdev app clone or the commands from the auth module.

Working within the application context matters because the CLI automatically detectes if there's an app manifest in the working directory. If so, it uses the app ID from the manifest to execute the command. However, the CLI also allows for a more flexible approach where you can work outside of the application context by passing the app ID and working directory in the command.

Working outside of the app context

To work outside of the application context you need to provide two optional parameters when running the commands:

For example, you can work on an app that lives in ./apps/my-app while being in a different directory (e.g. in ./).

$ txdev app verify --id=suLCxdG --dir=./apps/my-app

Getting started tutorial

This tutorial shows how to quickly add a new widget to an existing app using the Developer CLI.

1. Log in to Text Developer Console using the CLI.

txdev auth login --provider=accounts

2. Clone an existing app to your local environment.

The CLI will prompt you to select an app.

txdev app clone

After cloning, cd to the app directory so that you're in the same location as the livechat.config.json file. To work from a different location, see Working outside of the app context.

3. Add a new widget to the app.

The CLI will prompt you to specify the widget details such as widget placement and URL.

txdev app widgets add

4. Update the local app manifest.

After executing a command from the app module, you need to pull the changes to your local app manifest (txdev app pull) as it doesn't update automatically.

txdev app pull

5. See applied changes in the Developer Console.

txdev app open

app module

txdev app --help

Lists available command in the app module.

$ txdev app --help

Commands:
  txdev app create         create new app
  txdev app clone          clone app
  txdev app delete         delete app
  txdev app open           open app in browser
  txdev app pull           pull app manifest
  txdev app push           push app manifest
  txdev app verify         verify app manifest
  txdev app authorization  manage app authorization       
  txdev app monetization   manage app monetization        
  txdev app repository     manage app repository          
  txdev app deployment     manage app deployment          
  txdev app storage        manage app storage             
  txdev app properties     manage app properties          
  txdev app widgets        manage app widgets
  txdev app variables      manage app variables

txdev app clone

Fetches all the files related to an application registered in the Text Developer Console.

As a bare minimum, the command will fetch the app's manifest (livechat.config.json), but it can also download other files depending on what's set up for the application (repository, environment variables) in the Developer Console.

When to use the command:

• download all files of a newly created app
• update the app files after changes made in the Developer Console

$ txdev app clone

? select app › 
❯   Moments card sender
    Get Chats App
    My app

$ txdev app clone --id=suLCxdG-R

txdev app create

Creates a new application. It can be empty or bootstrapped from our Next.js SaaS template, which comes with a variety of features already set up.

💡txdev app create template is the fastest ways to create a fully working & deployed Text application.

$ txdev app create template

? template › 
❯   Nextjs SaaS boilerplate

$ txdev app create empty --name="Sample app" --product=livechat

txdev app pull

Fetches the app manifest (livechat.config.json) from the Developer Console.

This command will not pull other files related to the app. To download/update all app files, use the txdev app clone command.

$ txdev app pull

? select app › 
❯   Moments card sender
    Get Chats App
    My app

$ txdev app pull --id=suLCxdG-R

txdev app push

Pushes local changes made to the app manifest (livechat.config.json) to the Developer Console. The command will only push changes from the app manifest.

txdev app verify

Verify your local app manifest (livechat.config.json) against the one in the Text Developer Console. It compares only the app manifest, not all app files.

txdev app delete

Deletes an existing app from the Developer Console. Execute with caution.

txdev app open

Opens an application in the Developer Console.

txdev app authorization

Configures app authorization. It's the command-line equivalent of adding the App Authorization block in Developer Console. You will be prompted to select scopes by the CLI.

$ txdev app authorization add --type=server_side_app --redirectUri=https://myapp.com/

"authorization": {
      "clientId": "5c4d731184619046c915549fb09c1561",
      "type": "server_side_app",
      "redirectUri": "https://myapp.com/",
      "scopes": [
        {
          "scope": "archives_read",
          "required": true
        }
      ]
    }

txdev app widgets

Configures LiveChat or HelpDesk widgets. It's the command-line equivalent of the Agent App Widgets or Ticket Widgets block in the Developer Console.

$ txdev app widgets add --product=livechat --placement=plugin --url=https://myapp.com

    "widgets": {
      "5elheVKFzJ": {
        "url": "https://myapp.com",
        "placement": "plugin",
        "initialState": "" // returned for all placements, but has effect only for Chat Details
      }
    }

txdev app monetization

Configures app monetization. It's the command-line equivalent of the App Monetization block in the Developer Console. The CLI will guide you through the configuration.

$ txdev app monetization add

    "monetization": {
      "price": 100,
      "frequency": "monthly",
      "trialDays": 7,
      "charge": "organization"
    }

txdev app properties

Allows to remove LiveChat properties. It's the command-line equivalent of the Properties block in the Developer Console. The CLI allows you to edit app properties on published apps – execute with caution. The command doesn't support the add option -- this can be done in the Developer Console or via the Configuration API.

    "properties": {
      "chat_note": {
        "type": "string",
        "description": "",
        "access": {
          "thread": {
            "agent": ["write"],
            "customer": ["read"]
          }
        }
      }
    }

txdev app variables

Fetches environment variables stored in the Developer Console.

txdev app repository

$ txdev app repository link

txdev app deployment

Manages app deployment. It's the command-line equivalent of the Deployment block in the Developer Console. Support is provided for Netlify and Vercel.

$ txdev app deployment link

txdev app storage

Manages app storage. It's the command-line equivalent of the Storage block in the Developer Console.

$ txdev app storage link

auth module

txdev auth --help

Lists available commands in the auth module.

$ txdev auth --help

Commands:
  txdev auth login   login to provider
  txdev auth logout  logout from provider

txdev auth login

Log in to Text or to an external provider. Select the provider with arrows or specifying it explicitly in as the --provider param.

$ txdev auth login

❯   Text (unauthorized)
    GitHub  (unauthorized)
    Netlify  (unauthorized)
    Neon  (unauthorized)
    PlanetScale  (unauthorized)
    Vercel  (unauthorized)

$ txdev auth login --provider=github

txdev auth logout

Log out from Text or an external provider service. The command is analogous to the txdev auth login command.

Developer CLI on npm

To read more about the Developer SDK, visit its official page on npm.