CLI reference

ltc is the command-line client for a running Long Tail instance. It calls the same REST API as the dashboard, with the same RBAC. This page lists every command and flag. For a guided tour, see CLI.

Install

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

Or run it without a global install:

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

Global options

Option	Effect
-V, --version	Print the CLI version
-h, --help	Help for ltc or any command (ltc esc list --help)

ltc loads a .env file from the current directory when one exists.

Authentication

Command	Flag	Description
ltc login		Authenticate and store credentials. Prompts for any value not given.
	-s, --server <url>	Server URL (prompt default http://localhost:3000)
	-u, --username <name>	Username
	-p, --password <pass>	Password
ltc logout		Delete stored credentials
ltc status		Instance health and summary counts: pending escalations, active workers, pipeline tools, event transport

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

Credentials are stored in ~/.config/longtail/credentials.json with mode 0600. Tokens last 24 hours; before each call the CLI checks expiry and logs in again with the stored credentials when the token has expired.

Variable	Effect
LT_SERVER	Server URL
LT_TOKEN	Bearer token. When both LT_SERVER and LT_TOKEN are set, they replace stored credentials.
ANTHROPIC_API_KEY, OPENAI_API_KEY	Model key for ltc compile
LT_LLM_MODEL_PRIMARY	Default model for ltc compile (falls back to claude-sonnet-4-6)

Output modes

Most read commands take the same output flags:

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

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

Escalations

ltc escalations, alias ltc esc.

Command	Description
esc list	List escalations
esc get <id>	One escalation
esc lookups <id>	Resolve the versioned knowledge lookups pinned on an escalation
esc claim <id>	Claim for yourself
esc release <id>	Release back to the queue
esc resolve <id>	Resolve with a payload
esc find-by-meta <key> <value>	Find escalations by a metadata key and value, any status
esc claim-by-meta <key> <value>	Claim an escalation by a metadata key and value
esc resolve-by-meta <key> <value>	Resolve an escalation by a metadata key and value
esc resolve-by-ids <ids...>	Resolve a set of escalations by id
esc search-facets	Item-level faceted search within one role
esc claim-groups	Batch-claim complete origin groups in priority order
esc claim-by-facets	Batch-claim individual rows that match facets
esc aggregate-facets	Grouped analytics: membership at an instant, or dwell over a window
esc timeline <key> <value>	One entity’s ordered escalation-interval timeline

esc list

Flag	Description
--status <status>	pending, resolved or cancelled
--role <role>	One role
--roles <json>	Restrict to these roles, JSON array
--search <term>	Exact match on escalation id, workflow id or origin id
--facets <json>	Required metadata facets, JSON object (metadata @>)
--block <json>	Exclude rows containing any of these facet sets, JSON array
--range <json>	Numeric ranges over facets, e.g. '[{"facet":"confidence","op":"<=","value":0.7}]'
--exists <json>	Metadata keys that must be present, JSON array
--available <bool>	true: unclaimed or expired claims only; false: held now
--order-by <json>	Sort keys, e.g. '[{"field":"metadata.confidence","numeric":true,"direction":"asc"}]'
--limit <n>	Max results
--json, -q	Output mode

esc get, esc lookups

Flag	Description
--json	JSON output

esc claim, esc release, esc resolve

Command	Flag	Description
claim <id>	--duration <minutes>	Claim length in minutes
release <id>
resolve <id>	--data <json>	Resolver payload (required)

esc find-by-meta, esc claim-by-meta, esc resolve-by-meta

Command	Flag	Description
find-by-meta	--status <status>	Filter by status
	--limit <n>	Max results
	--json, -q	Output mode
claim-by-meta	--duration <minutes>	Claim length in minutes
	--assignee <external_id>	Claim for this user
	--meta <json>	Metadata to merge, JSON object
resolve-by-meta	--data <json>	Resolver payload
	--assignee <external_id>	Resolve for this user
	--meta <json>	Metadata to merge, JSON object

esc resolve-by-ids

Flag	Description
--payload <json>	Resolver payload (required)
--metadata <json>	Metadata to merge, JSON object

esc search-facets, esc claim-groups, esc claim-by-facets

Command	Flag	Description
search-facets	--role <role>	Role to search (required)
	--status <status>	Filter by status
	--available	Unclaimed or expired claims only
	--facets <json>	Required facets, JSON object
	--limit <n>	Max results
	--json, -q	Output mode
claim-groups	--role <role>	Role to claim from (required)
	--facets <json>	Required facets, JSON object
	--limit <n>	Max groups
	--duration <minutes>	Claim length in minutes
	--size-facet <key>	Metadata facet that declares group size
	--json	JSON output
claim-by-facets	--role <role>	Role to claim from (required)
	--facets <json>	Required facets, JSON object
	--limit <n>	Max rows
	--duration <minutes>	Claim length in minutes
	--all-or-none	Claim every matched row or none
	--json	JSON output

esc aggregate-facets

Membership at an instant (--as-of, default now) or dwell over a window (--window switches the measure).

Flag	Description
--role <role>	One role
--roles <json>	Several roles, JSON array. With no role at all the query spans every queue (global principals only).
--entity <key>	Entity facet key, e.g. serialNumber: scopes to every role that declares it
--group-state	Group by the derived state label (each role’s subtypes, or the role itself)
--group-columns <list>	Comma-separated: role, subtype, status
--group-facets <list>	Comma-separated metadata keys to group by
--facets <json>	Required facets, JSON object
--exists <json>	Metadata keys that must be present, JSON array
--prefix <json>	Case-insensitive prefix match on facet values, e.g. '{"serialNumber":"PRN"}'
--any-of <json>	Rows carrying any of these facet sets, JSON array (max 200)
--as-of <iso>	Membership at this instant; a past instant reconstructs the live set then
--window <json>	{"from":"...","to":"..."}: dwell over the window
--distinct-by <key>	Count distinct values of this facet (entities, not rows; membership only)
--live-statuses <list>	Comma-separated statuses counted as live (default pending)
--order-by <json>	Result-group order, e.g. '[{"field":"count","direction":"desc"}]'
--limit <n>, --offset <n>	Page the result groups
--json	JSON output

esc timeline

Gaps between intervals are untracked time.

Flag	Description
--entity <key>	Scope to every role that declares this entity facet. With neither --entity nor --roles, the query spans every queue (global principals only).
--roles <json>	Restrict to these roles, JSON array
--from <iso>, --to <iso>	Keep only intervals that overlap the window
--select-facets <list>	Comma-separated metadata keys to show per interval
--order <dir>	asc (default) or desc
--before <iso>	Strict upper bound on startedAt; with desc, pages a long history recent-first
--limit <n>	Max intervals
--json	JSON output

ltc esc list --status pending --role reviewer --limit 10
ltc esc list --facets '{"orderId":"ord-123"}'
ltc esc claim-by-meta orderId ord-123 --duration 30
ltc esc resolve-by-meta orderId ord-123 --data '{"approved": true}'
ltc esc aggregate-facets --entity serialNumber --group-state \
  --window '{"from":"2026-08-01T00:00:00Z","to":"2026-08-02T00:00:00Z"}'
ltc esc timeline serialNumber PRN-001 --entity serialNumber

Workflows

ltc workflows, alias ltc wf.

Command	Flag	Description
wf list	--include-system	Include system workflows
	--json, -q	Output mode
wf invoke <type>	--data <json>	Input data
	--json	JSON output
wf status <id>	--json	Status: running, completed, failed, or failed (terminated)
wf result <id>	--json	Result payload
wf envelopes <id>	--json	The workflow’s input and output envelopes; returns immediately
wf terminate <id>		Terminate a running workflow

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

Pipelines

YAML pipeline tools. ltc pipelines, alias ltc pip.

Command	Flag	Description
pip list	--status <status>	active, draft, deployed or archived
	--limit <n>	Max results
	--json, -q	Output mode
pip get <id>	--json	One pipeline
pip deploy <id>		Deploy a draft
pip invoke <id>	--data <json>	Input data
	--sync	Wait for the result
	--json	JSON output
pip archive <id>		Archive

Knowledge

ltc knowledge, alias ltc kb.

Command	Flag	Description
kb domains	--json, -q	List domains
kb list <domain>	--search <term>	Search by key or tag
	--limit <n>	Max results
	--json, -q	Output mode (-q prints keys)
kb get <domain> <key>	--version <n>	Read this immutable edition instead of the live entry
	--json	JSON output
kb versions <domain> <key>	--json, -q	Every edition of an entry, newest first
kb set <domain> <key> <path> <value>	--json	Set a value at a dot-path
kb remove <domain> <key> <path>		Remove the field at a dot-path
kb delete <domain> <key>		Delete the entry

ltc kb set research acme holiday "Founders Day"
ltc kb get research acme --version 2

MCP

Command	Flag	Description
mcp servers	--json, -q	Registered MCP servers
mcp tools <serverId>	--json, -q	A server’s tools (-q prints names)

Users

Admin only.

Command	Flag	Description
users list	--json, -q	All users
users get <id>	--json	One user
users props <id>		Show the user’s properties, or patch them atomically
	--set <key=value...>	Set a property; the value is parsed as JSON, else kept as a string. Repeatable.
	--remove <key...>	Delete a property. Repeatable.
	--rename <old=new...>	Rename a property and keep its value. Repeatable.
	--json	JSON output

Roles

Command	Flag	Description
roles list	--json, -q	Roles with schema version, member and workflow counts
roles schema <role>	--version <n>	Read an immutable snapshot instead of the latest
	--json	JSON output
roles schema-versions <role>	--json, -q	Version history, newest first
roles save-schema <role>	--file <path>	JSON Schema file; reads stdin when omitted
	--summary <text>	Change summary recorded on the new version
	--json	JSON output

A changed schema saves as the next version. Escalations pinned to an earlier version keep it.

Personas

Command	Flag	Description
personas list	--json, -q	Personas with role and holder counts
personas get <key>	--json	Role links and assignees
personas assign <key> <userId>	--json	Assign; idempotent
personas unassign <key> <userId>	--json	Unassign; removes only the memberships the persona sustains
personas for-user <userId>	--json	Personas a user holds and the composed role and scope map

Streams

Admin only. Browse engine and worker stream messages.

Command	Flag	Description
streams list	-n, --namespace <ns>	Schema namespace, e.g. durable (required)
	-s, --source <source>	engine or worker (required)
	--status <status>	pending, claimed, processed or dead_lettered
	--stream <name>	Stream name, partial match
	--type <type>	Message type (worker only)
	--limit <n>	Max results (default 25)
	--offset <n>	Pagination offset
	--sort <col>	created_at, stream_name, priority or id
	--order <dir>	asc or desc
	--json, -q	Output mode

Compiler

Command	Flag	Description
compile [target]		Compile durable TypeScript workflows (a file or a directory) to YAML DAGs
	--dry-run	List discovered workflows without compiling
	-o, --output <dir>	Output directory (default: next to the source)
	--model <model>	Model to use
	--function <name>	Workflow function name (detected when omitted)
	-q, --quiet	Exit codes only
init		Write a .env template for the compiler’s API key; leaves an existing .env alone

ltc compile src/workflows/ --dry-run
ltc compile src/workflows/review.ts --model claude-sonnet-4-6

Tip

In CI, export LT_SERVER and LT_TOKEN (for example a service account key) instead of running ltc login.

Related

CLI guideWorking the queue from a terminal.

HTTP referenceThe endpoints behind each command.

AnalyticsMembership, dwell and timelines.

Faceted routingSearch and claim by facets.