Hellotracks CLI

npm · @hellotracks/ht-cli

Hellotracks, from your terminal.

ht-cli is the official Hellotracks command-line interface. Create jobs, optimize routes, sync places, manage members and webhooks, rotate API keys — from your shell, your CI runner, or an AI coding agent. Output is structured, mutations preview before they run.

Install ht-cli

Contacta Ventas

ht-cli

$ht auth login

$ht jobs sync --file work-orders.csv --upsert-by externalId --dry-run

$ht routing optimize --account worker-uid --date today --solve

$ht webhooks set --event job.updated --url https://ops.example.com/hook

ht jobs syncdry-run

Plan summary

+142 created

~38 updated

!2 with warnings

Pending mutations

+Job · externalId=WO-2891

~Job · externalId=WO-2718 (address, priority)

!Job · externalId=WO-2719 (missing assigneeUsername)

Re-run without --dry-run to apply

ht resourcesauthjobsplacesmembersroutingwebhooksapikeysprofilesskills

For operators & engineers

Make it a script, not a click.

Inspect, create, import, and route work from scripts, terminals, and runbooks. The CLI is shaped for repeatable operations — the kind of work nobody should be clicking through twice.

Bulk sync without re-keying

ht jobs sync --file work-orders.csv --upsert-by externalId --dry-run

Pull from spreadsheets, CRMs, ERPs, or dispatch exports. `--dry-run` previews the plan; drop it to apply. Use `--continue-on-error` for resilient runs.

Optimize routes before dispatch

ht routing optimize --account worker-uid --date today --solve

Wire it to cron at 06:00. The optimizer solves the day; dispatch starts the morning with a ready plan instead of a backlog.

Rotate credentials with audit trail

ht apikeys create --label nightly-sync --source automation

Labeled, sourced keys land in `ht apikeys list`. Revoke the prior one with `ht apikeys revoke <id> --yes`. CI keeps secrets out of shell history via `HELLOTRACKS_API_KEY_FILE`.

For AI coding agents

An agent skill, not a wrapped API.

Most APIs hand agents a knife. ht-cli hands them a skill: an installable manifest, structured output, idempotent mutations, and dry-runs as the default verb. Agents reason about what they're about to do — and you keep the safety nets.

Install the skillht skills install

Drops the Hellotracks `SKILL.md` into both Codex (`~/.codex/skills/hellotracks/`) and Claude Code (`~/.claude/skills/hellotracks/`). Agents discover the whole command surface without being trained on it.

Structured, parseable output--output json | yaml | csv | ndjson

Every command supports stable machine-readable output. `--fields a,b,c` projects, `--sort -date` orders. Agents parse — they never screen-scrape.

Safe by default--dry-run · --profile prod · --confirm-profile prod

Mutations preview before they run. Profiles isolate environments. `--confirm-profile` is a hard guard against the wrong tenant. Agents preview, then commit — not the other way around.

Real workflows

What teams ship with ht-cli in the first week.

Not aspirational. These are the patterns platform engineers and dispatch leaders wire up the day they install the CLI.

CRM / work-orders feed dispatch nightly

A scheduled `ht jobs sync --upsert-by externalId` pulls open work-orders, creates or updates the matching jobs, and routes them to the right team — by externalId, so reruns are idempotent.

Routes are solved before sunrise

A 06:00 cron call to `ht routing optimize --account <uid> --date today --solve` hands dispatch a clean plan. No first-thing-in-the-morning routing scramble.

Webhooks fan out every job event

`ht webhooks set --event job.updated --url …` wires Hellotracks into billing, reporting, customer comms, Slack — configured once, listed with `ht webhooks list`, audited cleanly.

API keys rotate on schedule

Weekly CI runs `ht apikeys create --label weekly --source github-actions`, swaps the secret in the vault, then `ht apikeys revoke <prior> --yes`. Labels and sources make auditors happy.

Members & places stay in lockstep

HR pushes workforce.yaml; asset systems push customers.ndjson. `ht members sync --upsert-by username` and `ht places sync --upsert-by name` reconcile — no drift, no orphaned identities.

Profile guards keep production safe

`ht --profile production --confirm-profile production jobs sync …` fails loudly if the wrong profile is active. `ht profiles doctor` confirms each environment is healthy.

Coverage

Every operational surface, behind one binary.

ht-cli is built on the Hellotracks public API. The same primitives that power custom integrations become durable commands — humans, scripts, and agents share the same vocabulary.

Jobs

list · get · create · update · archive · restore · delete · import · sync · export

Members

list · get · create · update · delete · import · sync · export · columns · template

Places

list · get · create · update · import · sync · export · columns · template

Routing

optimize · --solve · --account · --date

Webhooks

list · set · per-event filters

API keys

list · create · revoke · delete · labels · sources

Profiles

list · create · use · doctor · --confirm-profile

Auth & skills

auth login · logout · whoami · validate · skills install

Install

One command. Every environment.

Install once, then use the same command surface from your laptop, CI runner, cron worker, or agent runtime. Auth is a single login — credentials go to your system keychain on macOS, or stay in HELLOTRACKS_API_KEY_FILE on servers.