Ethos CLI

Commander-based CLI for Ethos agent and table operations.

Install

npm install -g ethos-cli

Auth

The CLI can connect through your existing browser session:

ethos auth login
ethos auth status
ethos auth logout

Use --app-url if your frontend is not on the default local/prod URL:

ethos --api-url http://127.0.0.1:8001 auth login --app-url http://localhost:3001

When running from Codex, pass the current thread UUID to return to that thread after browser approval:

ethos auth login --codex-thread-id "$CODEX_THREAD_ID"

You can also configure auth with flags or environment variables:

export ETHOS_API_URL="https://api.ethos.hello-cluster.com"
export ETHOS_API_KEY="..."
export ETHOS_ORG_ID="..."

Every command also accepts --api-url, --api-key, --access-token, --org-id, and --json.

Skills

Ethos skills ship with the Ethos plugin from the cluster-software/cluster-plugins marketplace; the CLI no longer bundles or installs them. If a previous CLI version installed skills on this machine, inspect and clean them up with:

ethos skills list
ethos skills remove

Agent Commands

ethos agents list
ethos agents get <agent-id>

ethos agents create \
  --name "Company enricher" \
  --workflow-type company_enrichment \
  --ability web-search \
  --ability linkedin-company-lookup \
  --tool-preset browser

ethos agents configure <agent-id> --workflow-type people_sourcing --clear-abilities
ethos agents delete <agent-id>

Workflow/table compatibility is shown in --help: company tables support company enrichment columns and people sourcing, people tables support person enrichment columns. The CLI sends the configured request and lets backend validation decide the final result.

Org-scoped custom signals appear in ethos signals list with keys such as custom:<assignment-id> and configuration_mode: "managed". Use those keys with ethos signals pull and workflow commands exactly like built-in signals. Use the resulting sourcing job ID with ethos signals pull-status. Omit --config for managed custom signals; Ethos applies the organization’s current configuration revision server-side.

Organization members can manage their active organization’s complete assignment lifecycle through ethos custom-signals list|create|update|apply|preview|preview-status. The backend scopes every command to the active organization; apply atomically moves its active workflows to the current managed revision.

Table Commands

ethos tables list
ethos tables get <table-id>
ethos tables import-csv ./companies.csv --entity-type company
ethos tables import-csv ./people.csv --entity-type people

ethos tables source-people <table-id> \
  --filter <column-id>:contains:example \
  --input-column <column-id>

ethos tables columns create-agent <table-id> \
  --name "ICP fit" \
  --agent-id <agent-id> \
  --prompt "Score this account" \
  --output-field score \
  --output-field reason

ethos tables columns configure <table-id> <column-id> --name "New name"
ethos tables columns delete <table-id> <column-id>
ethos tables columns extract-json <table-id> <column-id>

ethos tables rows delete <table-id> <row-id>
ethos tables rows delete <table-id> 3 --by-index
ethos tables rows delete <table-id> 1 2 3 --by-index

ethos tables agent-edits apply <table-id> \
  --instruction "Delete rows that are no longer relevant" \
  --row-id <focused-row-id>

ethos tables cells set <table-id> <row-id> <column-id> --value "Manual note"
ethos tables cells set <table-id> <row-id> <column-id> --value '{"score":9}' --value-json

ethos tables runs start <table-id> <column-id> --scope first_5
ethos tables runs start <table-id> <column-id> --lower-range 1 --upper-range 50
ethos tables runs get <run-id>
ethos tables runs interrupt <run-id>

ethos tables source-people <company-table-id> \
  --view-id <view-id> \
  --agent-id <people-sourcing-agent-id> \
  --input-column <company-domain-column-id> \
  --targeting-brief "Find funding and finance contacts" \
  --created-by-codex

ethos tables create-people-table <company-table-id> \
  --column-id <people-finder-column-id> \
  --source-column <signal-context-column-id>

List And Campaign Commands

ethos lists import-from-table <people-table-id> \
  --linkedin-column "LinkedIn URL" \
  --custom-variable outreach_message \
  --custom-variable normalized_company_name

ethos campaigns attach-list <campaign-id> <list-id>

lists import-from-table creates contacts from table rows with valid LinkedIn person profile URLs or identifiers. It skips missing, invalid, and duplicate LinkedIn identities, reuses matching workspace contacts by default, and preserves source row IDs plus selected custom variables.

When stdout is not a TTY, output is JSON by default so coding agents can parse it reliably. Table-detail commands such as tables get, tables import-csv, and tables create-people-table include top-level table_id, column_ids, and row_ids in addition to the full nested objects. tables source-people includes top-level table_id, column_id, and run_id.