Documentation by ClonePartner

Start typing to search.

CLI Reference

Commands and flags

View Markdown

Reference every envoy CLI command and flag: task runs, validate, executor, job run, resume, status, validate, and logging behavior.

Commands and flags

The envoy binary runs tasks and job templates directly from YAML files, validates them, and starts an executor for remote task execution. Commands and flags below are defined in src/envoy.ts (yargs). Customer builds may rename the binary; the examples use envoy.

Run a task

The default command: the task name or path is the first positional argument.

envoy csv-to-sqlite \
  --config connectors.yaml \
  --arguments '{"input_file":"records.csv"}'

Global flags (also accepted by the subcommands below):

Flag Alias Type Default Description
--arguments -a string — JSON string of arguments to pass to the task.
--output -o string — Output format: ndjson (stream), json (collect all), none (silent).
--debug — boolean false Enable debug output to stderr (shows step input/config/output).
--log-level — string info Log level for structured logging to file: trace, debug, info, warn, error, silent.
--config -c string — Path to connectors.yaml config file.

Task data goes to stdout, so NDJSON output is safe to pipe:

envoy export-records --config connectors.yaml --output ndjson > records.ndjson

Invalid --arguments JSON exits with Error parsing --arguments JSON.

validate <task>

Validate a task file without running connector methods.

envoy validate tasks/csv-to-sqlite.yaml
Positional Type Required Description
task string Yes Name of the task to validate.

Exits 0 when valid, 1 otherwise. A valid result does not prove credentials, network access, or destination permissions.

executor

Start an executor server for remote task execution.

envoy executor \
  --control-plane https://envoy.example.com \
  --port 9090 \
  --max-concurrent 10 \
  --advertise-url http://executor.internal:9090
Flag Type Default Description
--control-plane array — Control plane URL(s) to register with. Repeat the flag or pass comma-separated values.
--port number 9090 Port to listen on.
--max-concurrent number 10 Maximum concurrent tasks.
--labels string — JSON string of labels for executor selection.
--advertise-url string — URL this executor advertises to the control plane (must be reachable by it).

The ENVOY_CONTROL_PLANES environment variable supplies additional comma-separated control-plane URLs; values from the flag and the variable are merged and deduplicated. At least one URL is required — otherwise the command exits with Error: at least one --control-plane URL or ENVOY_CONTROL_PLANES is required. Invalid --labels JSON exits with Error parsing --labels JSON.

See Control plane and executors for the deployment model.

job run <job-name>

Run a job template's DAG from the CLI.

envoy job run jobs/kitchen-sink.yaml --config connectors.yaml
envoy job run jobs/kitchen-sink.yaml --config connectors.yaml --tasks pull_accounts,push_accounts
envoy job run jobs/kitchen-sink.yaml --config connectors.yaml --tasks push_accounts --skip-deps
Positional / flag Alias Type Default Description
job-name — string (required) — Job name or path.
--tasks — string — Comma-separated list of tasks to run. Dependencies of selected tasks are resolved by default.
--skip-deps — boolean false Skip dependency resolution for selected tasks.
--max-concurrent — number — Max concurrent tasks per level.
--config -c string (required) — Path to connectors.yaml config file.

Use --skip-deps only when required upstream state already exists. The command prints a per-task status summary to stderr and exits 0 when the job status is completed, 1 otherwise.

job resume <run-file>

Resume a paused or failed job run from its state file.

envoy job resume .envoy/job-runs/example-1720000000000.json --config connectors.yaml
Positional / flag Alias Type Required Description
run-file — string Yes Path to the job run state file.
--config -c string Yes Path to connectors.yaml config file.

Exits 0 when the resumed run completes.

job status <run-file>

Print the status summary of a job run state file.

envoy job status .envoy/job-runs/example-1720000000000.json
Positional Type Required Description
run-file string Yes Path to the job run state file.

Shows the job status, start and completion times, and each task's status, duration, and messages.

job validate <file>

Validate a job template YAML file: structure, DAG, and job_config schema.

envoy job validate jobs/kitchen-sink.yaml
Positional Type Required Description
file string Yes Path to the job template YAML file.

Exits 0 when valid, 1 otherwise. See Job template YAML for the messages it can raise.

Debug output and structured logs

The two logging systems are independent:

  • --debug prints human-readable step input, config, and output to stderr, truncated at roughly 2000 characters per field. A single step can also set debug: true in the task YAML without the global flag.
  • --log-level controls structured JSON logging written by Pino to logs/envoy.log, relative to the working directory. silent disables it.

stdout carries task data only; keep stderr out of piped output files. See Testing and debugging tasks for interpreting both streams.