Documentation by ClonePartner

Start typing to search.

Getting Started

CLI quickstart

View Markdown

Validate and run an Envoy task from the command line with a connectors.yaml file and environment-backed secrets.

CLI quickstart

Goal

Run a task from the terminal with no server involved: write a connectors.yaml, validate the task, run it, and read its output. The CLI is the same Envoy binary the server runs — a task that works here works identically when triggered from the UI.

Prerequisites

  • The Envoy binary for your build (or a repository checkout, where bun src/main.ts stands in for the binary)
  • A task YAML file — this page uses the csv-to-sqlite task from Quickstart: build your first task

The CLI finds tasks by name in the tasks/ directory — a name can include a subdirectory path (for example migrations/gorgias/push-tickets).

Steps

1. Write connectors.yaml

Tasks declare connector slots with a type only, so the CLI needs a separate file that supplies each slot's actual configuration. Names must match the slot names in the task:

connectors:
  csv_source:
    type: csv
    config:
      directory: ./data
 
  db:
    type: sqlite
    config:
      path: ./envoy.db

Use ${ENV_VAR} placeholders for secrets — they resolve from the process environment at run time, and only for the connectors the task actually uses, so one shared connectors.yaml can hold entries for many tasks without requiring every variable to be set:

  d365:
    type: dynamics365
    config:
      base_url: ${D365_BASE_URL}
      tenant_id: ${TENANT_ID}
      client_id: ${CLIENT_ID}
      client_secret: ${CLIENT_SECRET}

The CLI also checks that each entry's type matches the slot's declared type and fails with a clear error when they differ. Full file format: connectors.yaml reference.

2. Validate the task

Validation checks YAML structure, step types, and slot references without touching any connector, so it needs no --config:

envoy validate csv-to-sqlite

3. Run it

envoy csv-to-sqlite --config connectors.yaml

Records that reach the end of the pipeline print to stdout as NDJSON by default. Useful variations:

# JSON array instead of NDJSON, or no output at all
envoy csv-to-sqlite --config connectors.yaml --output=json
envoy csv-to-sqlite --config connectors.yaml --output=none
 
# Pass runtime arguments (available as `arguments` in JSONata)
envoy csv-to-sqlite --config connectors.yaml --arguments='{"id": 123}'
 
# Show each step's input, config, and output on stderr
envoy csv-to-sqlite --config connectors.yaml --debug
Flag Alias Description
--config -c Path to the connectors.yaml file
--arguments -a JSON string of arguments passed to the task
--output -o Output format: ndjson (default), json, none
--debug Human-readable per-step trace on stderr
--log-level Structured log level: trace, debug, info (default), warn, error, silent

Argument values are coerced to the types the task declares in its arguments schema, and defaults apply when a declared argument is omitted.

Verify it worked

Check the output stream, or query the destination — for csv-to-sqlite, confirm rows landed:

sqlite3 envoy.db 'SELECT COUNT(*) FROM users;'

Running jobs from the CLI

Job templates run from the CLI too, with per-task selection and resumable state files:

envoy job run fiserv-migration --config connectors.yaml
envoy job run fiserv-migration --config connectors.yaml --tasks migrate_contacts --skip-deps
envoy job resume ./run-state/fiserv-migration-1234.json --config connectors.yaml
envoy job status ./run-state/fiserv-migration-1234.json

For job runs, connectors.yaml entries match the template-level connector names rather than task slot names. See CLI commands for the complete command set.