Helm CLI

Command line interface for Helm — run your business operations (projects, customers, billing, automations, and AI agents) from the terminal.

What is Helm?

Helm is the AI Operations Platform for founder-led business — AI agents take on the operational work so your team is free for the work that matters. Customers, projects, time and billing, documents, automations, and AI staff live in one place that runs itself.

Why a CLI?

The web app is where you think; the CLI is where you script. It exists for the work that is awkward to click through:

• Bulk import — CSV in, records out, with duplicate detection that runs once rather than per row.
• Scripting and CI — every command speaks JSON, so helm-ai task list pipes straight into jq.
• Working where your code lives — drop a .helm file in a repo and every command in that directory targets the right workspace automatically.
• Agents and automation — the same operations your AI staff perform, available to any script you write.

Installation

npm install -g @helm-ai/cli

Requires Node.js 20 or later. The binary is helm-ai.

If you want a shorter command, alias it yourself — alias h=helm-ai. The CLI deliberately does not claim the helm binary, which belongs to the Kubernetes package manager.

Quick Start

1. Get your API key

In Helm, go to Settings → API Keys and create one. Keys are scoped to a single workspace.

2. Log in

helm-ai login

Prompts for the key and saves it to ~/.helm/config.yaml. To skip the prompt (CI, scripts):

helm-ai login --api-key helm_sk_xxx

3. Check it worked

helm-ai whoami

Reports the resolved profile, the workspace it points at, and why that profile was chosen — which is usually the answer when a command touches the wrong workspace.

Profiles

An API key is scoped to one workspace, so each workspace gets its own profile.

helm-ai login --profile acme          # save a second workspace
helm-ai profile list                  # what is saved
helm-ai profile use acme              # change the default
helm-ai profile current               # which one applies here, and why

A profile is chosen in this order, highest first:

1. --profile <name> on the command
2. HELM_PROFILE environment variable
3. A .helm file, searched upward from the current directory
4. defaultProfile in ~/.helm/config.yaml

The .helm file is the useful one: put a single profile name in it at the root of a repo, and everything run inside that repo targets the matching workspace without a flag.

HELM_API_KEY, HELM_API_URL and HELM_WORKSPACE_ID override the fields of whichever profile is selected. They do not change which profile is selected.

Commands

Every resource follows the same shape — list, get <id>, create, update <id>, and whatever verbs that resource genuinely has.

| Group | What it covers | |---|---| | project, task, time | Delivery: projects, tasks, comments, time entries | | account, contact, deal, pipeline | Customers: companies, people, and the sales pipeline | | invoice, estimate, product | Money: billing documents and the product catalog | | doc | Rich-text documents, folders, and pages | | calendar | Events and meetings | | form, sequence, email | Capture and follow-up | | workflow, template | Automations and reusable project structures | | agent | AI staff — schedules, objectives, and runs | | import | Bulk import of people, accounts, deals and tasks from CSV/JSON | | login, logout, whoami, profile, config | Credentials and settings |

Run helm-ai --help for the full list, or helm-ai <group> --help for one group.

Examples

# What is on your plate
helm-ai task list --status in_progress

# Add something without leaving the terminal
helm-ai task create --title "Fix the webhook retry" --project <project-id>

# Close it out
helm-ai task complete TASK-42
helm-ai task comment TASK-42 "Shipped in 1.4.2"

# Log the time against it
helm-ai time log --task TASK-42 --duration 90m --description "Webhook retry fix"

# Bulk import people — dry-run first, which is the default
helm-ai import people ./leads.csv
helm-ai import people ./leads.csv --apply

Output formats

helm-ai task list --output json     # table | json | ndjson | csv | yaml

The default depends on where output is going: a table when you are looking at a terminal, JSON when the output is piped or redirected. So this works without a flag:

helm-ai task list | jq '.[] | select(.priority == "high") | .title'

Single-record commands (helm-ai task get <id>) default to JSON, since one record does not table well.

Scripting notes

• Imports are a dry run until you say otherwise. helm-ai import <entity> <file> reports what it would do; add --apply to write. Entities: people, accounts, deals, tasks.
• Rate limits are handled for you. The client retries on 429 (honouring Retry-After) and on 5xx with exponential backoff, five attempts maximum. You do not need a retry loop.
• Exit codes mean something. Any failure exits non-zero with the reason on stderr, so set -e behaves.
• Output stays clean when piped. The startup banner is suppressed whenever output is not a terminal.

Environment variables

| Variable | Effect | |---|---| | HELM_API_KEY | Overrides the selected profile's key | | HELM_API_URL | Overrides the API endpoint | | HELM_WORKSPACE_ID | Overrides the workspace | | HELM_PROFILE | Selects which profile to use |

Set HELM_API_KEY in CI rather than committing a config file.

Related

• @helm-ai/mcp-server — the same operations as MCP tools, for Claude and other MCP-compatible assistants.
• Documentation

License

MIT