Hydra ETL
Build your first job
Get started›Hydra CLI›Lesson 1
Lesson 1 of 11 · Explore CLI

Explore the hdrctl command surface

Start with global help, read the command grammar, and build a map of every action available from the Hydra CLI.

hdrctl --helpabout 10 minuteshdrctl available

1. Objective

Goal

Run hdrctl --help, understand the [OPTIONS] COMMAND [ARGS]... grammar, distinguish global options from commands, and learn how to request focused help before executing an unfamiliar action.

Prerequisites

  • hdrctl is available in your terminal.
  • No Hydra project is required for the global help command.
  • Use a terminal wide enough to read the command descriptions comfortably.

2. Steps

01Open the global help

Objective

Ask Hydra to describe its complete top-level command surface.

Actions

  1. Open a terminal.
  2. Run the global help command.
hdrctl --help
What you should see

The usage line appears first, followed by a short description, the main commands, global options, and the complete command list.

Usage: hdrctl [OPTIONS] COMMAND [ARGS]...

hdrctl — Hydra ETL Control CLI

Manage your declarative ETL pipelines with ease.

02Read the command grammar

Objective

Understand which parts of the usage line are optional and which part selects the action.

Actions

  1. Read the usage line from left to right.
  2. Separate global [OPTIONS] from the COMMAND.
  3. Treat [ARGS]... as values owned by the selected command.
hdrctl [OPTIONS] COMMAND [ARGS]...
What you should see

A valid invocation starts with hdrctl, may add a global option, selects one command, then passes that command its own arguments.

hdrctl --lang en list jobs/
       └ option ┘ └ command arguments
Read brackets as notation

[OPTIONS] and [ARGS]... describe optional input. Do not type the square brackets themselves.

03Read the global options

Objective

Recognize the options that belong to hdrctl itself and therefore appear before a command.

Actions

  1. Find the Options section.
  2. Use --version when you need the active CLI version.
  3. Use --lang en or --lang es to choose the interface language.
  4. Use -h as the short form of --help.
hdrctl --version
hdrctl --lang en --help
hdrctl -h
What you should see 
Options:
  --version    Show the version and exit.
  --lang LANG  Interface language (en, es)
  -h, --help   Show this message and exit.

04Map the five main commands

Objective

Connect the core job lifecycle to the commands highlighted by global help.

Actions

  1. Read the Main commands section.
  2. Follow the lifecycle from creation to execution.
hdrctl --help
What you should see 
Main commands:
  run       Execute an ETL pipeline
  init      Create a new job from a template
  test      Validate a job configuration
  validate  Strict YAML DSL validation
  list      List jobs in current directory

Use each command for one distinct question:

  • init — what should Hydra create?
  • list — what jobs are present here?
  • validate — does the YAML obey the DSL?
  • test — can the declared job configuration be used?
  • run — execute the pipeline.

05Tour the complete command list

Objective

Discover the operational commands that sit beside the five core job commands.

Actions

  1. Find the complete Commands section below the options.
  2. Identify commands for cleanup, the API backend, and multi-job workflows.
hdrctl --help
What you should see

The complete help surface contains nine commands:

Usage: hdrctl [OPTIONS] COMMAND [ARGS]...

  hdrctl — Hydra ETL Control CLI

  Manage your declarative ETL pipelines with ease.

  Main commands:
    run       Execute an ETL pipeline
    init      Create a new job from a template
    test      Validate a job configuration
    validate  Strict YAML DSL validation
    list      List jobs in current directory

Options:
  --version    Show the version and exit.
  --lang LANG  Interface language (en, es)
  -h, --help   Show this message and exit.

Commands:
  clear     Examples: hydra clear
  init      Available templates: basic — Simple CSV (default) csv — CSV...
  list      Examples: hydra list hydra list jobs/
  run       PATH Job directory (default: current directory)
  serve     Démarre l'API FastAPI Hydra (Studio backend).
  test      Examples: hydra test .
  validate  Examples: hydra validate .
  workflow  Manage and execute Hydra workflows (multi-job DAG).

Group the commands by intent:

  • Create and inspect: init, list.
  • Check and execute: validate, test, run.
  • Operate: clear, serve.
  • Orchestrate: workflow.
Descriptions are orientation, not full syntax

The global list tells you which command to choose. The command's own help tells you its paths, options, and examples.

06Open focused command help

Objective

Move from the global map to the exact contract of one command without executing it.

Actions

  1. Choose a command from the global list.
  2. Append --help or -h.
  3. Try the same pattern with init, run, and workflow.
hdrctl init --help
hdrctl run --help
hdrctl workflow --help
What you should see

Each command prints its own usage line, arguments, options, and examples, then exits without creating or running anything.

Usage: hdrctl COMMAND [OPTIONS] [ARGS]...

Options:
  -h, --help  Show this message and exit.

Keep this pattern throughout the track: when a command is unfamiliar, inspect its focused help before supplying a path or option.

Tips and traps

Start broad with hdrctl --help, then narrow with hdrctl COMMAND --help.

Global options such as --lang belong before the command name.

-h and --help are inspection tools. Use them before supplying paths or executing jobs.

The one-line command description is only a summary. Read focused help before assuming defaults.

The usage line is a grammar: brackets mean optional input and the ellipsis allows more arguments.

Do not type the documentation brackets in [OPTIONS] or [ARGS]....

3. Checklist

VerificationExpected result
hdrctl --helpUsage, description, options, and commands are visible
Usage grammar[OPTIONS] COMMAND [ARGS]... is understood
Global options--version, --lang, and --help are identified
Main commandsrun, init, test, validate, and list
Complete command listclear, serve, and workflow are also identified
Focused helphdrctl COMMAND --help prints details without executing the command

4. Troubleshooting

SymptomCauseFix
hdrctl: command not foundThe CLI is not available in the active shellActivate the environment where Hydra is installed, then reopen the terminal if needed
No such commandThe command name is misspelled or placed before a global optionReturn to hdrctl --help and copy the command name exactly
--lang is rejected after a commandIt is a global optionPlace it before the command: hdrctl --lang en list
A subcommand starts doing work--help was omittedStop the command if safe, then rerun it as hdrctl COMMAND --help
The help output is truncatedThe terminal viewport is too smallScroll up or enlarge the terminal before choosing a command

5. Next lesson

You now know how to navigate the CLI without guessing. The next lesson uses hdrctl init to create the first job and inspect the files produced by its template.

Create a job Back to the course map

Close by

0 / 0 on this page