# Commands and flags

> Source: https://docs.clonepartner.com/cli/commands/

<!-- sources: src/envoy.ts, src/logger.ts, references/envoy/debugging.md -->

# 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.

```bash
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:

```bash
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.

```bash
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.

```bash
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](/deployment/control-plane-and-executors/) for the deployment model.

## `job run <job-name>`

Run a job template's DAG from the CLI.

```bash
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.

```bash
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.

```bash
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.

```bash
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](/reference/job-templates/) 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](/building/testing-and-debugging/) for interpreting both streams.

## Related

- [connectors.yaml format](/cli/connectors-yaml/) — the file `--config` points at
- [CLI quickstart](/getting-started/cli-quickstart/) — first run end to end
- [Job template YAML](/reference/job-templates/) — the files `job run` and `job validate` consume
- [Testing and debugging tasks](/building/testing-and-debugging/) — debug output and structured logs in practice