CLI - Blue Docs

The Blue CLI is a single blue binary that talks to the same GraphQL API your browser does. Anything you can do in the app, you can do from your terminal — manage workspaces, records, lists, tags, custom fields, automations, checklists, comments, files, and users.

Open source and contributions welcome

The CLI is fully open source. Source, issues, and releases live at github.com/heyblueteam/cli. PRs are very welcome.

What it’s good for

Bulk operations — create, update, or move hundreds of records in seconds
Scripting and CI/CD — wire Blue into deploy pipelines, cron jobs, or shell scripts
Quick reads — blue records list --workspace <id> --done false without leaving your terminal
Migrations and backfills — pipe data from anywhere into Blue, or the other way around
Feeding AI agents — give Claude Code, Cursor, or any shell-aware tool a direct line into your Blue data

Install

macOS — Homebrew

brew install heyblueteam/tap/blue-cli

Windows — Scoop

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

Linux — prebuilt binary

Grab the latest blue_linux_amd64.tar.gz (or arm64) from the releases page, extract, 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 OS — `go install`

If you have Go 1.21+ installed, the fastest path to the latest source build:

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

This installs a blue binary to $GOBIN (or $GOPATH/bin). Make sure that’s on your $PATH.

From source

If you want to hack on it:

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 talks to the Blue API using a Personal Access Token. The fastest way to set it up:

blue init

This prompts for your credentials and saves them to ~/.config/blue/config.env.

Generating a Personal Access Token

Log in to Blue
Go to Account → API
Click Create Token
Copy the Token ID and Token Secret — you’ll need both

Keep your token secret safe

Your token secret is only shown once when created. Store it securely. If you lose it, you’ll need to create a new token.

Manual configuration

If you’d rather not use blue init, drop a .env file in your project directory (takes priority over the global config):

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

Your COMPANY_ID is the org slug from your Blue URL — for example, acme from blue.cc/org/acme.

Verify

blue workspaces list --simple

If you see a list of workspaces, you’re set.

Command overview

All commands follow the pattern blue <group> <action> [flags]. Run blue <command> --help for full details on any command.

Group	Aliases	What it manages
`workspaces`	`ws`	Workspaces (aka projects): create, update, delete, list
`records`	`rec`	Records (aka todos): CRUD, move, count, filter, custom-field queries
`lists`		Lists within a workspace
`tags`		Tags: create, list, add to records
`fields`	`cf`	Custom fields, field options, and field groups
`automations`	`auto`	Workflow automations with triggers and actions
`checklists`		Checklists and checklist items on a record
`comments`		Record comments (plain text or HTML)
`users`		Users, invitations, and roles
`dependencies`	`deps`	Record-to-record dependencies
`files`		Bulk file downloads
`completion`		Generate shell completions

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"

Custom field format

SELECT fields use option IDs with a trailing comma: "cf_priority:option_high,". Numbers and text go in as-is: "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 "[email protected]" \
  --email-subject "Task done"

Download all files from a workspace

blue files download --use-env --output "backup.zip" --parallel 10

Shell completion

The CLI ships with completion for bash, zsh, fish, and PowerShell. To enable for zsh:

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

Run blue completion --help for other shells.

Updating

Use the same package manager you installed with:

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

For source builds, git pull && go build -o blue ./cmd/blue in your clone.