CLI

ltc gives an operator the same escalation boundary the dashboard and SDK use: find a row, claim it, resolve it, and the waiting workflow resumes. It also runs workflows, edits knowledge and lists MCP servers. This page covers install, sign-in and the everyday commands. Every command and flag is in the CLI reference.

Install

npm install -g @hotmeshio/long-tail
ltc --help

Or run it without a global install:

npx -p @hotmeshio/long-tail ltc --help

ltc login

Prompts for the server URL, username and password, then stores credentials in ~/.config/longtail/credentials.json with file mode 0600.

ltc login --server https://lt.acme.dev --username superadmin --password "$LT_PASSWORD"

Short forms: -s, -u, -p. Use this in CI and scripts.

export LT_SERVER=https://lt.acme.dev
export LT_TOKEN=eyJ...

Environment variables take precedence over stored credentials.

The token lasts 24 hours. ltc checks expiry before each call and refreshes from stored credentials. ltc logout clears them. ltc status shows pending escalations, active workers, pipeline tools and the event transport.

Escalations

ltc esc list --status pending --role reviewer --limit 10
ltc esc get <id>
ltc esc claim <id> --duration 60
ltc esc resolve <id> --data '{"approved": true}'
ltc esc release <id>

--search matches an escalation, workflow or origin id exactly. For a value inside metadata, use the by-metadata commands or --facets:

ltc esc find-by-meta orderId ord-123 --status pending
ltc esc claim-by-meta orderId ord-123 --assignee ext-user-42
ltc esc resolve-by-meta orderId ord-123 --data '{"approved": true}'
ltc esc resolve-by-ids <id1> <id2> --payload '{"approved": true}'

--assignee acts on behalf of a user by external id. --meta merges outcome facets into the row.

Faceted queries and claims

esc list takes the full facet query as JSON flags:

ltc esc list --status pending \
  --facets '{"flags":"too_short"}' \
  --range '[{"facet":"confidence","op":"<=","value":0.7}]' \
  --order-by '[{"field":"metadata.confidence","numeric":true,"direction":"asc"}]'

The claim primitives take a required --role:

ltc esc search-facets --role pick --available --facets '{"zone":"cold"}'
ltc esc claim-groups --role pick --limit 4 --size-facet orderSize
ltc esc claim-by-facets --role pack-station --facets '{"state":"ready"}' --limit 4 --all-or-none

See Faceted routing for what each does.

Analytics

# How every entity spent the window, one row per state
ltc esc aggregate-facets --entity serialNumber --group-state \
  --window '{"from":"2026-08-01T00:00:00Z","to":"2026-08-02T00:00:00Z"}'

# One entity's ordered interval timeline
ltc esc timeline serialNumber PRN-001 --entity serialNumber

--window measures dwell. Without it, aggregate-facets measures membership now or at --as-of. See Analytics.

Workflows

ltc wf list
ltc wf invoke reviewContent --data '{"content": "test"}'
ltc wf status <workflowId>
ltc wf result <workflowId>
ltc wf terminate <workflowId>

YAML pipeline tools have their own group:

ltc pip list --status active
ltc pip invoke <id> --data '{"url": "https://example.com"}' --sync

Knowledge

ltc kb domains
ltc kb list catalog --search widgets
ltc kb get catalog widgets
ltc kb versions catalog widgets
ltc kb set catalog widgets price.list 12.5
ltc kb remove catalog widgets legacy_data

Every change to an entry’s data mints a new edition. See Lookups.

MCP, roles and personas

ltc mcp servers
ltc mcp tools <serverId>

ltc roles list
ltc roles schema reviewer --version 3
ltc roles save-schema reviewer --file schema.json --summary "Added lotNumber"

ltc personas assign shift-lead <userId>
ltc personas for-user <userId>

A schema save that changes the form creates the next version. In-flight rows keep the version they pinned.

Output modes

Every list command prints a table by default:

Flag	Output
(none)	Formatted table
`--json`	Raw JSON for `jq` and scripts
`-q`, `--quiet`	IDs only, one per line

ltc esc list --json | jq '.escalations[].id'
ltc pip list -q | xargs -I {} ltc pip get {}

Aliases

Full	Short
`ltc escalations`	`ltc esc`
`ltc workflows`	`ltc wf`
`ltc pipelines`	`ltc pip`
`ltc knowledge`	`ltc kb`

Configuration

Variable	Use
`LT_SERVER`	Server URL, overrides stored credentials
`LT_TOKEN`	Bearer token, overrides stored credentials
`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`	Needed by `ltc compile`
`LT_LLM_MODEL_PRIMARY`	Model for `ltc compile`

CLI referenceEvery command and flag.

IdentityService accounts and API keys for scripts.

Resolve by domain key

Claim complete groups

CLI