---
title: "Customer's Canvas Hub CLI | Customer's Canvas Hub"
canonical: "https://customerscanvas.com/docs/hub/dev-center/samples/cchub-cli/"
---

# Customer's Canvas Hub CLI

> The source code of the Customer's Canvas Hub CLI application is available at:

https://github.com/aurigma/cchub-cli

This is a command-line interface (CLI) application built with Node.js and TypeScript. It demonstrates how to construct Customer's Canvas designs programmatically through the Design Atoms SDK and submit them to the Customer's Canvas Hub backend.

The sample demonstrates the following tasks:

1. Authenticating with the Customer's Canvas Hub API using two authentication modes.
2. Constructing a design programmatically with the Design Atoms SDK.
3. Submitting the design to the Customer's Canvas Hub backend.

## Technical details

The application is coded in Node.js 18+ and TypeScript. The build produces a single distributable CLI file, `dist/cchub-cli.js`, with all dependencies bundled. No `node_modules` folder is required at runtime.

## Getting started

### Set up your Customer's Canvas tenant

Before you start, prepare the data you need to use the API. Specify this data in the configuration, as described below.

1. **Tenant ID**. Log in to your Customer's Canvas tenant, go to **Settings** > **Tenant**, and copy the number from the **ID** field (see the [Tenant Settings Topic](https://customerscanvas.com/docs/hub/admin-guide/settings/tenant.md)).
2. **Client ID**/**Secret**. Register your application using the Client Credentials authentication scheme in **Settings** > **External Apps** (see the [External Apps Settings Topic](https://customerscanvas.com/docs/hub/admin-guide/settings/external-apps.md)).
3. **API Gateway**. Depending on your hosting environment, it's https://api.customerscanvashub.com, https://api.eu.customerscanvashub.com, or https://api.au.customerscanvashub.com (see the [API Gateway](https://customerscanvas.com/docs/hub/dev-center/api.md#api-gateway) topic).

### Clone repo

Clone the repository with the following command:

```bash
git clone https://github.com/aurigma/cchub-cli.git
```

### Configure app

Create a `.env` file. There are two supported authentication modes, and you can configure either one or both.

Common settings:

```sh
CCHUB_BASEURL=https://customerscanvashub.com
CCHUB_TENANTID=xxx  # Tenant ID from the Settings > Tenant
CCHUB_TOKENREFRESTIMEBEFOREEXPIRATIONSEC=60
APP_LOGLEVEL=info
```

#### Option 1. Client Credentials

Use this mode for non-interactive CLI usage when the app can authenticate directly with `client_id` and `client_secret`.

```sh
CCHUB_CLIENT_CREDENTIALS_CLIENTID=xxxxxxxxxx
CCHUB_CLIENT_CREDENTIALS_CLIENTSECRET=xxxxxxxxxxx
```

#### Option 2. Interactive Authorization Code login

Use this mode when you want to sign in through the browser and let the CLI keep a local session.

```sh
CCHUB_AUTHORIZATION_CODE_CLIENTID=xxxxxxxxxx
CCHUB_AUTHORIZATION_CODE_SCOPE=Assets_full Private_assets_update Projects_full Storefronts_read Templates_full StorefrontUsers_full Tenants_read TenantUsers_read Artifacts_full RenderingJobs_full
CCHUB_AUTHORIZATION_CODE_CALLBACK_HOST=127.0.0.1
CCHUB_AUTHORIZATION_CODE_CALLBACK_PORT=53682
CCHUB_AUTHORIZATION_CODE_CALLBACK_PATH=/oauth/callback
```

Notes:

- `CCHUB_AUTHORIZATION_CODE_SCOPE` should contain only resource scopes required by Customer's Canvas Hub.
- The CLI automatically adds `openid profile email offline_access` to the interactive login request.
- See supported scopes through the discovery endpoint https://customerscanvashub.com/.well-known/openid-configuration (see `scopes_supported`).
- If your identity provider requires an exact redirect URI, use a fixed callback port and register a URI like `http://127.0.0.1:53682/oauth/callback`.
- If `CCHUB_AUTHORIZATION_CODE_CALLBACK_PORT` is omitted, the CLI uses a random free port.

#### If both modes are configured

The CLI uses authentication in this order:

- If a persisted interactive session exists and is still valid, it is used.
- If the interactive session exists but the access token is expired, the CLI tries to refresh it.
- If there is no usable interactive session, the CLI falls back to Client Credentials if they are configured.

### Run

Install the dependencies:

```bash
npm install
```

Run the CLI application:

```bash
npm start -- <command> <subcommand> <args>
```

By running `npm start` without arguments, you get a list of all supported commands.

Get help:

```bash
npm start -- help
```

or

```bash
npm start -- help <command>
```

or (for options of specific subcommands):

```bash
npm start -- help <command> <subcommand> --help
```

For interactive browser-based login:

```bash
npm start -- auth login
```

To inspect or clear the persisted session:

```bash
npm start -- auth status
npm start -- auth logout
```

If you have any problems or questions, create a ticket in the [helpdesk](https://customerscanvas.com/account/cases/add).