CLI

The Blue command-line interface (CLI) is a blue binary that uses the same GraphQL API as the Blue app. It supports the same operations as the app. Use it to manage workspaces, records, lists, tags, custom fields, automations, checklists, comments, documents, forms, dashboards, reports, webhooks, files, and users.

CLI uses

• Bulk operations: Create, update, or move hundreds of records in seconds.
• Scripts and CI/CD: Add Blue commands to deployment pipelines, scheduled jobs, or shell scripts.
• Terminal queries: Run commands such as blue records list --workspace <id> --done false.
• Migrations and backfills: Send data to or retrieve data from Blue.
• Reporting: Queue CSV exports, read report data, and recalculate dashboard charts.
• Admin and audit: Review activity, list webhooks, and export a file inventory.
• AI assistants: Let shell-aware tools such as Claude Code and Cursor use Blue data.

Install

macOS with Homebrew

brew install heyblueteam/tap/blue-cli

Windows with Scoop

scoop bucket add heyblueteam https://github.com/heyblueteam/scoop-bucket
scoop install blue-cli

Linux prebuilt binary

Download the latest blue_linux_amd64.tar.gz or arm64 archive from the releases page. Extract it and move blue into your $PATH:

curl -L https://github.com/heyblueteam/cli/releases/latest/download/blue_linux_amd64.tar.gz | tar xz
sudo mv blue /usr/local/bin/

Any operating system with go install

If Go 1.21 or newer is installed, run:

go install github.com/heyblueteam/cli/cmd/blue@latest

This command installs blue in $GOBIN or $GOPATH/bin. Add that directory to your $PATH.

From source

To build the CLI from source, run:

git clone https://github.com/heyblueteam/cli.git
cd cli
go build -o blue ./cmd/blue
sudo mv blue /usr/local/bin/

Authentication

The CLI authenticates with a Personal Access Token. Start the configuration process with:

blue init

The command requests your credentials and saves them to ~/.config/blue/config.env.

For scripts and AI agents, pass all three credentials to skip every prompt:

blue init --client-id <id> --auth-token <secret> --company-id acme

Generate a Personal Access Token

1. Log in to Blue.
2. Open Account > API.
3. Select Create Token.
4. Copy the Token ID and Token Secret.

Manual configuration

To configure the CLI without blue init, add a .env file to your project directory. This file takes priority over the global configuration:

API_URL=https://api.blue.app/graphql
AUTH_TOKEN=your_token_secret
CLIENT_ID=your_token_id
COMPANY_ID=your_company_slug

Set COMPANY_ID to the organization slug from your Blue URL. For example, use acme for blue.app/org/acme.

These optional variables are also read:

Values resolve in this order, highest first: process environment, then ./.env, then ~/.config/blue/config.env.

Verify

blue whoami
blue doctor

blue whoami prints the current user, company, API endpoint, and default workspace. blue doctor runs read-only checks on your configuration, credentials, API connectivity, and company access. Add --workspace <id-or-slug> to also check workspace access.

Command overview

Commands use the pattern blue <group> <action> [flags]. Run blue <command> --help for details about a command. Workspace flags accept an ID or a slug.

Global flag

--company <slug> overrides the active company for one command:

blue --company acme workspaces list --simple

Set a default workspace

Most commands need --workspace. To stop typing it, set a default:

blue context use acme                    # Set the default company
blue context use acme/product-roadmap    # Set the company and the workspace
blue context set-workspace product-roadmap
blue context current                     # Show the active defaults
blue context clear                       # Remove the default workspace

After this, blue records list uses the default workspace. An explicit --workspace always wins.

To work with more than one organization, add each one and switch between them:

blue company add acme
blue company add other-org
blue company use acme
blue company list

Find IDs

Most commands need IDs. The ids group converts names to IDs. Each subcommand accepts --search, --limit, and --format text|json|csv.

blue ids workspace --search CRM
blue ids list --workspace crm
blue ids field --workspace crm --search Priority
blue ids tag --workspace crm --format csv
blue ids user --search alex --format json
blue ids record --workspace crm --search "Launch plan"

To find records by name, use search:

blue search "launch" --workspace crm --done false --limit 50

To open a page in your browser instead, use open. Add --print to print the URL:

blue open workspace crm
blue open record rec_abc123 --workspace crm
blue open dashboard dsh_abc123
blue open report rpt_abc123 --print

Examples

List open records assigned to a user

blue records list --workspace crm --done false --assignee user_abc123 --simple

Create a record with custom fields

blue records create \
  --workspace crm \
  --list lst_123 \
  --title "Follow up with Acme Corp" \
  --assignees user_abc123 \
  --custom-fields "cf_priority:option_high,;cf_value:50000"

Bulk-create records from a CSV

while IFS=, read -r title assignee; do
  blue records create -w crm -l lst_123 -t "$title" --assignees "$assignee"
done < leads.csv

Filter records by custom field

blue records list \
  --workspace crm \
  --custom-field "cf_value:GT:50000" \
  --stats

Available operators: EQ, NE, GT, GTE, LT, LTE, IN, NIN, CONTAINS, IS, NOT.

Create an automation

blue automations create \
  --workspace crm \
  --trigger-type "TODO_MARKED_AS_COMPLETE" \
  --action-type "SEND_EMAIL" \
  --email-to "ops@example.com" \
  --email-subject "Task done"

Read the comments on a record

blue comments list --record rec_abc123 --limit 50
blue comments create --record rec_abc123 --workspace crm --text "Progress update"

Set up a new workspace from one file

The bootstrap group creates lists, tags, and custom fields from a JSON file. Use it to repeat a known-good process in a new workspace.

blue bootstrap template > workspace.json     # Start from a template
blue bootstrap export --workspace crm > workspace.json   # Or copy an existing workspace
blue bootstrap apply --file workspace.json --confirm

Without --confirm, apply is a dry run. It shows what it would create.

Forms

Use the forms group to manage the public forms in a workspace.

# List forms in a workspace
blue forms list --workspace crm --simple

# Create a form with fields
blue forms create \
  --workspace crm \
  --title "Lead intake" \
  --list lst_new_leads \
  --primary-color "#2563eb" --theme dark --active \
  --field "type=title;name=Full name;required=true;position=1000" \
  --field "type=custom;customField=cf_budget;name=Budget;required=true;position=2000"

# Or define the fields in a JSON file
blue forms create --workspace crm --title "Lead intake" --fields-file ./form-fields.json

# Update routing or look-and-feel
blue forms update --form frm_abc123 --primary-color "#2563eb" --active true

# Add, update, and remove fields one at a time
blue forms fields list   --form frm_abc123 --workspace crm
blue forms fields add    --form frm_abc123 --workspace crm --type custom --custom-field cf_phone --name "Phone"
blue forms fields delete --field ff_abc123 --workspace crm --confirm

# Print the public submit link
blue forms url --form frm_abc123 --workspace crm

# Copy or delete a form
blue forms copy   --form frm_abc123 --workspace crm
blue forms delete --form frm_abc123 --workspace crm --confirm

Field types are title, description, tags, startedAt, duedAt, and custom. Only custom needs a customField ID.

These commands can create workspaces and intake forms in one script. They can also keep form configuration in version control.

Documents and wiki pages

blue documents list --workspace crm --simple
blue documents list --workspace crm --wiki true
blue documents get --document doc_abc123 --content
blue documents create --workspace crm --title "Runbook" --content '<h1>Runbook</h1>'
blue documents create --workspace crm --title "Handbook" --wiki --content-file handbook.html
blue documents update --document doc_abc123 --title "New title"
blue documents delete --document doc_abc123 --confirm

Reports, dashboards, and charts

Reports

blue reports list --simple
blue reports create --title "Open work" --workspaces "crm,support" --filter-json '{"done":false}'
blue reports data --report rpt_abc123 --limit 50
blue reports aggregate --report rpt_abc123 --field cf_value:number
blue reports share --report rpt_abc123 --users "user1:EDITOR,user2:VIEWER"
blue reports refresh --report rpt_abc123
blue reports duplicate --report rpt_abc123 --title "Working copy"
blue reports export --report rpt_abc123
blue reports delete --report rpt_abc123 --confirm

Dashboards and charts

blue dashboards list --workspace crm --simple
blue dashboards create --title "Sales Dashboard"
blue dashboards get --dashboard dsh_abc123
blue dashboards update --dashboard dsh_abc123 --title "Revenue"
blue dashboards update --dashboard dsh_abc123 --allow-viewer-chart-data true
blue dashboards share --dashboard dsh_abc123 --users "user1:EDITOR"

--allow-viewer-chart-data controls whether people with VIEWER access can open the records behind a chart.

blue charts list --dashboard dsh_abc123
blue charts get --chart cht_abc123 --format json

blue charts create --dashboard dsh_abc123 --title "Total Revenue" --display-type stat \
  --workspace crm --field cf_value --function SUM --display currency --currency USD
blue charts create --dashboard dsh_abc123 --title "By Assignee" --display-type bar \
  --workspace crm --group-by ASSIGNEE
blue charts create --dashboard dsh_abc123 --title "Status by list" --display-type bar \
  --workspace crm --group-by TODO_STATUS --breakout TODO_LIST --stack-mode PERCENT

blue charts preview --dashboard dsh_abc123 --title "By status" --display-type bar \
  --workspace crm --group-by TODO_STATUS
blue charts edit --chart cht_abc123 --title "New title" --display-type line --width 4 --height 3
blue charts recalculate --charts "cht_1,cht_2"
blue charts delete --chart cht_abc123 --confirm

blue charts preview renders a chart without saving it.

Display types are bar, line, area, row, leaderboard, table, pie, funnel, combo, stat, progress, and gauge. Aggregation functions are COUNT, COUNTA, SUM, AVERAGE, AVERAGEA, MIN, and MAX. Charts group by PROJECT, ASSIGNEE, TAG, CUSTOM_FIELD, TODO, TODO_LIST, TODO_STATUS, or a TODO_* date field. With CUSTOM_FIELD, also pass --group-field or --breakout-field.

For charts with more than one metric, or with targets, trends, or bands, pass the exact GraphQL input as JSON. This form is the better choice for scripts and AI agents, because it keeps the nested structure of the API:

blue charts create --input chart.json --format json
cat chart.json | blue charts create --input - --format json
blue charts edit --input edit.json --format json

Payload flags and --input cannot be used together.

Saved views

blue saved-views list --workspace crm --simple
blue saved-views get --view viw_abc123
blue saved-views apply --view viw_abc123          # Prints the view configuration
blue saved-views update --view viw_abc123 --shared true
blue saved-views delete --view viw_abc123 --confirm

CSV exports

Blue builds the CSV on the server and makes it available when it is ready.

blue exports records --workspace crm
blue exports records --workspace crm --done false --q launch --assignees "user1,user2"
blue exports records --workspace crm --filter-json '{"hasDueDate":true}'
blue exports report --report rpt_abc123
blue exports chart --chart cht_abc123
blue exports template --workspace crm          # CSV import template

Files

blue files inventory > files.csv                          # All company files as CSV
blue files inventory --workspace crm --output files.csv
blue files inventory --workspace crm --search invoice
blue files download                                       # Interactive mode
PROJECT_ID=crm blue files download --use-env --output "backup.zip" --parallel 10

--use-env is fully non-interactive. It needs PROJECT_ID in the environment and fails immediately if it is missing. FOLDER_ID is optional; unset means the root folder.

Activity

blue activity                                             # Company-wide
blue activity --workspace crm --since 7d
blue activity --workspace crm --category CREATE_TODO,CREATE_COMMENT
blue activity --user user_abc123 --limit 50 --format json
blue activity record rec_abc123 --workspace crm
blue activity record rec_abc123 --workspace crm --type comments

Webhooks

blue webhooks list --simple
blue webhooks events                                      # Show the supported event names
blue webhooks create --name "Production sync" \
  --url https://example.com/webhooks/blue \
  --events TODO_CREATED,COMMENT_CREATED
blue webhooks update --webhook whk_abc123 --enabled false
blue webhooks disable --webhook whk_abc123
blue webhooks delete --webhook whk_abc123 --confirm

To develop against webhooks, run a local receiver and check the signature:

blue webhooks listen --port 8080 --secret whsec_123
blue webhooks verify-signature --secret whsec_123 --signature <hex> --body-file payload.json

An empty --events value means all events. An empty --workspaces value means all workspaces.

Custom domains and email

blue domains domains list
blue domains domains create --name app.example.com --type APPLICATION
blue domains domains verify --name app.example.com
blue domains smtp list
blue domains smtp verify --host smtp.example.com --port 587 --username user --password pass
blue domains templates list
blue domains templates get --type INVITATION
blue domains templates test --template tpl_abc123 --email you@example.com

Raw API access

If a command does not exist for what you need, send the GraphQL request directly:

blue api query --raw 'query { __typename }'
blue api query --file query.graphql --variables '{"id":"workspace_123"}'
blue api schema                # Print the bundled schema
blue api schema --introspect   # Introspect the live endpoint

The CLI also carries an offline copy of the API documentation:

blue docs
blue docs list records
blue docs search "automation trigger"
blue docs show records/list-records
blue docs records/list-records --open

Output formats

Support for --format is not the same on every command:

Other commands, such as records list and workspaces list, print text only. Most listing commands accept --simple for short output.

blue ids record --workspace crm --format json | jq '.[].id'
blue ids user --format csv > users.csv
blue reports data --report rpt_abc123 --format json
blue records list --workspace crm --simple

Shell completion

The CLI supports completion for bash, zsh, fish, and PowerShell. To enable zsh completion, run:

blue completion zsh > "${fpath[1]}/_blue"

For other shells, run blue completion --help.

Updating

Update the CLI with the installation method that you used:

brew upgrade blue-cli                                   # macOS
scoop update blue-cli                                   # Windows
go install github.com/heyblueteam/cli/cmd/blue@latest   # Go install

For a source build, run git pull && go build -o blue ./cmd/blue in the cloned repository.

Check the installed version with blue version.

Links

• Source and releases: github.com/heyblueteam/cli
• API reference: blue.app/api
• Developer platform: blue.app/platform/developer