---
title: "Jetstack CLI | Jetstack AI Docs"
description: "Install the Jetstack AI CLI to browse HubSpot portals, import and deploy assets, run audits and explore your library from the terminal or Claude Code."
url: "https://jetstack.ai/docs/developers/cli/"
---

# Jetstack CLI

The Jetstack CLI lets you work with your Jetstack AI account from the terminal. It calls the same [REST API](https://jetstack.ai/api) as the app, using your access token. Output is JSON by default, so scripts and AI agents can read it.

|              |                                                                    |
| ------------ | ------------------------------------------------------------------ |
| **Package**  | [`@jetstackai/cli`](https://www.npmjs.com/package/@jetstackai/cli) |
| **Command**  | `jetstackai`                                                       |
| **Requires** | Node.js 18 or later                                                |

## Install

Terminal window

```
npm   install   -g   @jetstackai/cli
```

Check it installed:

Terminal window

```
jetstackai   --version
```

## Authenticate

You need a Jetstack access token.

1. In the Jetstack app, go to **Settings → Access Tokens** and create a token. Pick the scopes you need. The **Operator** preset covers everything on this page.

2. Copy the token. It starts with `jsai_` and is shown only once.

3. Run the login command:

   Terminal window

   ```
   jetstackai   auth   login
   ```

4. Enter your **Instance ID** and **Access Token** when asked.

   - **Instance ID:** enter `default`. If your organisation runs on a dedicated Jetstack instance, paste the Instance ID shown in **Settings → Access Tokens → Connection Details** instead.
   - **Access Token:** paste your `jsai_…` token.

The CLI checks the token and shows your organisation and scopes:

```
Validating credentials...
✓ Connected successfully
   Organization: org_xxx
   Scopes: portals:read, assets:read, ...
```

Credentials are saved in `~/.jetstackai/config.json`. Run `jetstackai auth logout` to remove them. For more on tokens and scopes, see [Authentication](https://jetstack.ai/docs/developers/authentication).

Anyone who can read `~/.jetstackai/config.json` can use your token. Don’t commit it or share it. Each person on your team should log in with their own token.

## Quick Start

Copy a workflow from one portal to another:

Terminal window

```
# 1. Find your portals and their IDs
jetstackai   portals   list   --format   table

# 2. See the workflows in the source portal
jetstackai   hubspot   browse   <sourcePortalId>   workflows   --format   table

# 3. Import two of them into your library, and wait for the import to finish
jetstackai   import   start   --portal   <sourcePortalId>   --assets   workflows:101,workflows:102   --name   "Lead routing"
jetstackai   import   status   <taskId>   --watch

# 4. Get the library IDs of the imported workflows
jetstackai   assets   list   --type   workflows   --portal   <sourcePortalId>   --format   table

# 5. See what needs mapping in the target portal
jetstackai   mapping   structure   --source   <sourcePortalId>   --target   <targetPortalId>   --assets   workflows:<libraryId>

# 6. Deploy, and wait for the deploy to finish
jetstackai   deploy   start   --name   "Lead routing to prod"   --source   <sourcePortalId>   --target   <targetPortalId>   \
   --assets   workflows:<libraryId>   --mapping   '{"assets":[],"properties":[],"pipelines":[],"owners":[]}'
jetstackai   deploy   status   <taskId>   --watch
```

`import start` takes **HubSpot IDs**, from `hubspot browse`. `mapping` and `deploy` take **library IDs**, from `assets list`. Portal IDs always come from `portals list`.

## Command Reference

Run `jetstackai --help`, or `jetstackai <command> --help`, for the built-in help.

### Output Formats

Most commands take `--format json` (the default) or `--format table`. `mapping` commands and `profiles detail` always print JSON. `profiles mermaid` and `profiles preview-mermaid` print the diagram as text by default, or JSON with `--format json`.

To make tables the default, set `defaultFormat` in `~/.jetstackai/config.json`:

```
{
   "instanceId" :  "default" ,
   "accessToken" :  "jsai_..." ,
   "defaultFormat" :  "table"
}
```

### Authentication

| Command                  | What it does                                                        |
| ------------------------ | ------------------------------------------------------------------- |
| `jetstackai auth login`  | Saves your Instance ID and access token after checking them.        |
| `jetstackai auth status` | Checks the connection and shows your organisation and scopes.       |
| `jetstackai auth whoami` | Shows the saved Instance ID, a masked token and the default format. |
| `jetstackai auth logout` | Deletes the saved credentials.                                      |

### Portals

| Command                   | What it does                                              |
| ------------------------- | --------------------------------------------------------- |
| `jetstackai portals list` | Lists the HubSpot portals connected to your organisation. |

### HubSpot Browse

| Command                                            | What it does                                                |
| -------------------------------------------------- | ----------------------------------------------------------- |
| `jetstackai hubspot browse <portalId> <assetType>` | Lists assets in a connected portal, with their HubSpot IDs. |

Asset types: `workflows`, `forms`, `emails`, `lists`, `pipelines`, `pages`, `templates`, `blogPosts`, `hubdbTables`, `properties`, `propertyGroups`, `customObjects`.

For `properties` and `pipelines`, add `--object-type`:

Terminal window

```
jetstackai   hubspot   browse   <portalId>   properties   --object-type   contacts
```

### Import

| Command                                                                      | What it does                                                                                     |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `jetstackai import start --portal <id> --assets <type:id,...> --name <name>` | Imports assets from HubSpot into your library. Returns a task ID.                                |
| `jetstackai import status <taskId>`                                          | Shows an import’s progress for each asset. Add `--watch` to check every 5 seconds until it ends. |

`--assets` takes comma-separated `type:hubspotId` pairs, such as `workflows:101,forms:202`.

To group the imported assets into a module, add `--create-module`. Set its name with `--module-title` (it defaults to the import name) and add `--module-description` if you like.

Terminal window

```
jetstackai   import   start   --portal   <portalId>   --assets   workflows:101,forms:202   --name   "Q1 import"   \
   --create-module   --module-title   "Lead capture"
```

### Assets

| Command                  | What it does                  |
| ------------------------ | ----------------------------- |
| `jetstackai assets list` | Lists assets in your library. |

Options: `--type <type>`, `--portal <portalId>`, `--limit <n>` (default 100) and `--start-after <cursor>` for the next page.

### Modules

| Command                       | What it does                                              |
| ----------------------------- | --------------------------------------------------------- |
| `jetstackai modules list`     | Lists your modules. Add `--limit <n>` to cap the results. |
| `jetstackai modules get <id>` | Shows one module with its assets.                         |

### Mapping

| Command                                                                           | What it does                                                                                                                     |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `jetstackai mapping structure --source <id> --target <id> --assets <type:id,...>` | Shows what must be mapped before deploying: properties, owners, pipelines and more. Add `--modules <id,...>` to include modules. |
| `jetstackai mapping destinations --target <id> --type <type>`                     | Lists the options in the target portal for one mapping type.                                                                     |

For `mapping destinations`, add `--object-type <objectTypeId>` for properties and pipelines (for example `0-1` for contacts, `0-3` for deals), and `--from-object` and `--to-object` for association labels.

Terminal window

```
jetstackai   mapping   destinations   --target   <targetPortalId>   --type   properties   --object-type   0-1
```

### Deploy

| Command                                                                                    | What it does                                                                                    |
| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `jetstackai deploy start --name <name> --source <id> --target <id> --assets <type:id,...>` | Deploys library assets to the target portal. Returns a task ID.                                 |
| `jetstackai deploy status <taskId>`                                                        | Shows a deploy’s progress for each asset. Add `--watch` to check every 5 seconds until it ends. |

`deploy start` also takes:

- `--mapping <json>`: the mapping, as a JSON string. Its shape is `{"assets":[], "properties":[{"objectTypeId","sourceName","targetName"}], "pipelines":[{"objectTypeId","sourceId","targetId","stages":[{"sourceId","targetId"}]}], "owners":[{"sourceId","targetId"}]}`.
- `--modules <id,...>`: modules to deploy.
- `--properties <id,...>`: property sets to deploy.

`deploy start` writes to the target HubSpot portal. Check the output of `mapping structure` first, and test on a sandbox portal when you can.

### Tasks

| Command                     | What it does                                     |
| --------------------------- | ------------------------------------------------ |
| `jetstackai tasks list`     | Lists import and deploy tasks.                   |
| `jetstackai tasks get <id>` | Shows one task with its progress for each asset. |

Filter `tasks list` with `--type` (`import-assets` or `deploy-assets`), `--status` (`pending`, `processing`, `completed`, `incomplete` or `failed`) and `--limit <n>`.

An `incomplete` task has finished, but some assets were skipped or have unresolved dependencies. `--watch` on `import status` and `deploy status` stops on `completed`, `failed` or `cancelled`, so for a task that may end `incomplete`, check it with `tasks get`.

### Audits

| Command                                                                                  | What it does                                                                            |
| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `jetstackai audits list-blocks`                                                          | Lists the blocks you can put in an audit template.                                      |
| `jetstackai audits list-templates`                                                       | Lists Jetstack’s built-in templates and your own. Add `--limit <n>` to cap the results. |
| `jetstackai audits get-template <id>`                                                    | Shows one template and its blocks.                                                      |
| `jetstackai audits create-template --name <name> --blocks <id,...> --report-type SIMPLE` | Creates a template. Also takes `--description`, `--goals` and `--branding-id`.          |
| `jetstackai audits run --name <name> --template <id> --portal <id>`                      | Starts an audit. Add `--watch` to wait until it finishes.                               |
| `jetstackai audits status <auditRunId>`                                                  | Shows an audit’s status. Add `--watch` to wait until it finishes.                       |
| `jetstackai audits data <auditRunId>`                                                    | Prints the full results of a completed audit.                                           |

`list-blocks` filters: `--report-type` (`SIMPLE` or `ADVANCED`), `--category` (`general`, `sales_hub`, `marketing_hub`, `service_hub`, `automation` or `reporting`), `--essential-only` and `--default-only`.

`audits run` also takes `--audit-mode quick` (the default, current period only) or `--audit-mode full` (adds trend data), and `--branding-id` to override the template’s branding.

Only `SIMPLE` templates run from the CLI. `ADVANCED` templates need the [Chrome extension](https://jetstack.ai/docs/extension/audits).

Terminal window

```
jetstackai   audits   list-blocks   --report-type   SIMPLE   --format   table
jetstackai   audits   run   --name   "Q1 audit"   --template   <templateId>   --portal   <portalId>   --watch
jetstackai   audits   data   <auditRunId>   >   audit.json
```

### Profiles

Profiles describe assets in a structured way (properties used, dependencies, enrolment criteria, actions) so you or an agent can find the right asset for a job.

| Command                                                       | What it does                                                                                                       |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `jetstackai profiles search`                                  | Searches profiles of assets in your library. Filter with `--type`, `--object-type`, `--portal` and `--limit`.      |
| `jetstackai profiles scan <portalId> <assetType>`             | Profiles assets straight from a HubSpot portal. Results are cached for 24 hours; add `--fresh` to re-read HubSpot. |
| `jetstackai profiles scan-all <assetType>`                    | Profiles one asset type across every connected portal. Also takes `--fresh`.                                       |
| `jetstackai profiles detail <type> <id>`                      | Prints the full stored data for an imported asset, including its HubSpot definition and dependencies.              |
| `jetstackai profiles mermaid <id>`                            | Prints an imported workflow as a Mermaid flowchart.                                                                |
| `jetstackai profiles preview-mermaid <portalId> <workflowId>` | Prints a HubSpot workflow as a Mermaid flowchart, without importing it.                                            |

Profile asset types are `workflows`, `lists`, `forms`, `emails` and `pipelines`. `scan` and `scan-all` also take `--object-type`, such as `Contact` or `Deal`.

Terminal window

```
jetstackai   profiles   scan-all   workflows   --object-type   Contact   --format   table
jetstackai   profiles   preview-mermaid   <portalId>   <hubspotWorkflowId>
```

## Use the CLI with Claude Code

The CLI package includes a ready-made setup for [Claude Code](https://docs.anthropic.com/en/docs/claude-code): a `CLAUDE.md` file that teaches Claude Code the `jetstackai` commands, and a set of slash commands for common jobs.

1. Install the CLI and run `jetstackai auth login`, as above.

2. Copy the setup files into your project:

   Terminal window

   ```
   SETUP = "$( npm  root  -g )/@jetstackai/cli/claude-code-setup"
   cp   " $SETUP /CLAUDE.md"   /path/to/your/project/
   cp   -r   " $SETUP /.claude"   /path/to/your/project/
   ```

   If your project already has a `CLAUDE.md`, add the contents of the Jetstack one to it instead of overwriting it.

3. Open Claude Code in the project and run `/jetstack-setup`. It checks the CLI is installed and signed in, and lists your portals.

| Slash command            | What it does                                                                                                                                                          |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/jetstack-setup`        | Checks the install and sign-in, then lists your portals.                                                                                                              |
| `/jetstack-status`       | Reports on your connection, portals, assets, modules and tasks.                                                                                                       |
| `/jetstack-browse`       | Browses assets in a HubSpot portal.                                                                                                                                   |
| `/jetstack-import`       | Walks you through an import.                                                                                                                                          |
| `/jetstack-deploy`       | Walks you through a deploy, including mapping.                                                                                                                        |
| `/jetstack-assets`       | Explores your asset library.                                                                                                                                          |
| `/jetstack-modules`      | Explores your modules.                                                                                                                                                |
| `/jetstack-audit-report` | Writes a full audit report from a completed audit. This one uses the [MCP server](https://jetstack.ai/docs/developers/mcp) tools, so connect it in Claude Code first. |

Commit `CLAUDE.md` and `.claude/` to share them with your team. Each person still installs the CLI and logs in with their own token.

Claude Code asks before running each command unless you allow it. Keep that on for `import start`, `deploy start` and `audits run`.

## Related

[MCP Server ](https://jetstack.ai/docs/developers/mcp)Connect Claude, ChatGPT or Cursor to Jetstack directly.

[API Reference ](https://jetstack.ai/api)The REST endpoints behind every CLI command.

[Authentication ](https://jetstack.ai/docs/developers/authentication)Access tokens, scopes and Instance IDs.
