CLI quickstart

The Envoy CLI executes task and job YAML without the web control plane. It is useful for local development, validation, automation, and controlled one-off runs.

The examples assume the supplied executable is on PATH as envoy and that you are in a bundle containing tasks/ and jobs/.

1. Prepare input data

Create data/users/users.csv:

id,first_name,last_name,email,status
1,Ada,Lovelace,ada@example.com,active
2,Grace,Hopper,grace@example.com,active

2. Create connector configuration

Create connectors.yaml outside version control:

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

Connector names must match the slots used by the standalone task. Types must also match.

3. Validate the task

envoy validate csv-to-sqlite

Validation checks the YAML structure and compiles expressions. It does not contact connectors and cannot catch errors that depend on live data.

4. Run the task

envoy csv-to-sqlite \
  --config connectors.yaml \
  --output none

The task creates the users table in quickstart.db and upserts both rows. Use --debug if you need human-readable step input, config, and output on stderr.

Pass runtime arguments

Tasks with an arguments schema accept a JSON object:

envoy my-task \
  --config connectors.yaml \
  --arguments='{"limit": 10, "dry_run": true}'

Argument values are coerced to the types declared by the task before execution.

Use environment variables

Connector environment references are resolved only for connector slots used by the task:

connectors:
  destination:
    type: postgres
    config:
      connection_string: ${DESTINATION_DATABASE_URL}

export DESTINATION_DATABASE_URL='postgres://...'
envoy my-task --config connectors.yaml

Next

• CLI commands, configuration, and logs covers task and job commands, output channels, and job state files.
• Task structure documents the complete YAML schema.
• Troubleshooting covers diagnostics and common runtime failures.