CLI Reference

Cyclonetix provides a comprehensive command-line interface (CLI) for managing workflows, tasks, and system operations. This reference documents all available commands and options.

Basic Usage

cyclonetix [OPTIONS] [COMMAND]

Global Options

Option Description
--config <FILE> Path to configuration file (default: config.yaml)
--help, -h Show help information
--version, -v Show version information
--ui Start only the UI server
--agent Start only an agent process
--orchestrator Start only an orchestrator process

Common Commands

cyclonetix

Starting Cyclonetix without a command runs all components (orchestrator, agent, and UI) in development mode.

cyclonetix --config my-config.yaml

cyclonetix schedule-task

Schedule a task for execution.

cyclonetix schedule-task <TASK_ID> [OPTIONS]

Options:

Option Description
--context <CONTEXT> Context to use for execution
--param <KEY=VALUE> Task parameter override (can be specified multiple times)
--param-set <SET> Parameter set to apply
--env <KEY=VALUE> Additional environment variable (can be specified multiple times)
--run-id <ID> Custom run ID (auto-generated if not specified)
--queue <QUEUE> Override the task’s default queue
--wait Wait for task completion and show logs
--timeout <SECONDS> Timeout for task execution in seconds
--retries <COUNT> Number of retries on failure
--retry-delay <SECONDS> Delay between retries in seconds
--ignore-dependencies Execute without resolving dependencies
--git-ref <REF> Git reference for task definition

Example:

cyclonetix schedule-task process_data \
  --context production \
  --param BATCH_SIZE=200 \
  --param MODE=full \
  --env DATA_DATE=2023-11-01

cyclonetix schedule-dag

Schedule a DAG for execution.

cyclonetix schedule-dag <DAG_ID> [OPTIONS]

Options:

Option Description
--context <CONTEXT> Context to use for execution
--param <TASK_ID.KEY=VALUE> Task parameter override (can be specified multiple times)
--env <KEY=VALUE> Additional environment variable (can be specified multiple times)
--run-id <ID> Custom run ID (auto-generated if not specified)
--wait Wait for DAG completion
--timeout <SECONDS> Timeout for DAG execution in seconds
--git-ref <REF> Git reference for DAG definition

Example:

cyclonetix schedule-dag etl_pipeline \
  --context production \
  --param extract_data.LIMIT=1000 \
  --param load_data.MODE=incremental \
  --wait

cyclonetix schedule-dag-file

Schedule a DAG from a file (without requiring it to be in the tasks directory).

cyclonetix schedule-dag-file <FILE_PATH> [OPTIONS]

Options are the same as schedule-dag.

Example:

cyclonetix schedule-dag-file ./my-custom-dag.yaml \
  --context production

Task and DAG Management

cyclonetix list-tasks

List available tasks.

cyclonetix list-tasks [OPTIONS]

Options:

Option Description
--filter <PATTERN> Filter tasks by name or ID
--queue <QUEUE> Filter tasks by queue
--format <FORMAT> Output format (table, json, yaml)

Example:

cyclonetix list-tasks --filter "data_*" --format json

cyclonetix list-dags

List available DAGs.

cyclonetix list-dags [OPTIONS]

Options:

Option Description
--filter <PATTERN> Filter DAGs by name or ID
--format <FORMAT> Output format (table, json, yaml)

Example:

cyclonetix list-dags --format table

cyclonetix show-task

Show details of a specific task.

cyclonetix show-task <TASK_ID> [OPTIONS]

Options:

Option Description
--format <FORMAT> Output format (yaml, json)
--show-dependencies Show task dependencies
--git-ref <REF> Git reference for task definition

Example:

cyclonetix show-task process_data --show-dependencies

cyclonetix show-dag

Show details of a specific DAG.

cyclonetix show-dag <DAG_ID> [OPTIONS]

Options:

Option Description
--format <FORMAT> Output format (yaml, json)
--show-tasks Show tasks in the DAG
--git-ref <REF> Git reference for DAG definition

Example:

cyclonetix show-dag etl_pipeline --show-tasks

Execution Management

cyclonetix list-runs

List current and recent workflow runs.

cyclonetix list-runs [OPTIONS]

Options:

Option Description
--status <STATUS> Filter by status (pending, running, completed, failed)
--dag <DAG_ID> Filter by DAG ID
--limit <COUNT> Maximum number of runs to show
--since <TIME> Show runs since time (e.g., 1h, 2d, 2023-01-01)
--format <FORMAT> Output format (table, json, yaml)

Example:

cyclonetix list-runs --status running --since 12h

cyclonetix show-run

Show details of a specific workflow run.

cyclonetix show-run <RUN_ID> [OPTIONS]

Options:

Option Description
--format <FORMAT> Output format (table, json, yaml)
--show-tasks Show tasks in the run
--follow Follow the run and show updates

Example:

cyclonetix show-run etl_pipeline_20231105_123456 --show-tasks --follow

cyclonetix cancel-run

Cancel a running workflow.

cyclonetix cancel-run <RUN_ID> [OPTIONS]

Options:

Option Description
--force Force cancel even if in critical section

Example:

cyclonetix cancel-run etl_pipeline_20231105_123456

cyclonetix rerun

Rerun a failed or completed workflow.

cyclonetix rerun <RUN_ID> [OPTIONS]

Options:

Option Description
--failed-only Rerun only failed tasks
--from-task <TASK_ID> Rerun from a specific task
--reset-params Reset parameters to original values

Example:

cyclonetix rerun etl_pipeline_20231105_123456 --failed-only

Agent Management

cyclonetix list-agents

List active agents.

cyclonetix list-agents [OPTIONS]

Options:

Option Description
--format <FORMAT> Output format (table, json, yaml)
--show-tasks Show tasks assigned to agents

Example:

cyclonetix list-agents --show-tasks

cyclonetix agent-status

Show detailed status of an agent.

cyclonetix agent-status <AGENT_ID> [OPTIONS]

Options:

Option Description
--format <FORMAT> Output format (table, json, yaml)

Example:

cyclonetix agent-status agent_20231105_123456

Queue Management

cyclonetix list-queues

List task queues and their status.

cyclonetix list-queues [OPTIONS]

Options:

Option Description
--format <FORMAT> Output format (table, json, yaml)
--show-tasks Show tasks in queues

Example:

cyclonetix list-queues --show-tasks

cyclonetix purge-queue

Purge all tasks from a queue.

cyclonetix purge-queue <QUEUE> [OPTIONS]

Options:

Option Description
--confirm Confirm the operation without prompting

Example:

cyclonetix purge-queue default --confirm

System Management

cyclonetix check-health

Check the health of the Cyclonetix deployment.

cyclonetix check-health [OPTIONS]

Options:

Option Description
--backend Check backend connectivity
--agents Check agent health
--orchestrators Check orchestrator health
--all Check all components

Example:

cyclonetix check-health --all

cyclonetix verify-config

Verify the configuration without starting the server.

cyclonetix verify-config [OPTIONS]

Options:

Option Description
--config <FILE> Path to configuration file

Example:

cyclonetix verify-config --config production.yaml

cyclonetix clear-history

Clear execution history.

cyclonetix clear-history [OPTIONS]

Options:

Option Description
--days <DAYS> Clear history older than specified days
--status <STATUS> Clear runs with specific status (completed, failed)
--confirm Confirm the operation without prompting

Example:

cyclonetix clear-history --days 30 --status completed --confirm

Advanced Commands

cyclonetix backfill

Run a DAG for a date range (backfilling).

cyclonetix backfill <DAG_ID> [OPTIONS]

Options:

Option Description
--start-date <DATE> Start date (YYYY-MM-DD)
--end-date <DATE> End date (YYYY-MM-DD)
--context <CONTEXT> Context to use for execution
--max-parallel <COUNT> Maximum parallel executions
--wait Wait for all executions to complete

Example:

cyclonetix backfill daily_etl \
  --start-date 2023-01-01 \
  --end-date 2023-01-31 \
  --context production \
  --max-parallel 5

cyclonetix import

Import tasks or DAGs from external files.

cyclonetix import <TYPE> <FILE_PATH> [OPTIONS]

Where <TYPE> is one of: task, dag, context, parameter-set.

Options:

Option Description
--overwrite Overwrite existing definitions
--validate Validate without importing

Example:

cyclonetix import task ./external-tasks/*.yaml --validate

cyclonetix export

Export tasks or DAGs to external files.

cyclonetix export <TYPE> <ID> <FILE_PATH> [OPTIONS]

Where <TYPE> is one of: task, dag, context, parameter-set.

Options:

Option Description
--format <FORMAT> Output format (yaml, json)
--include-dependencies Include dependencies when exporting

Example:

cyclonetix export dag etl_pipeline ./exports/etl_pipeline.yaml --include-dependencies

Next Steps