hydra-cli

hydra-cli lets you talk to the JSON API of hydra on the command line. It includes commands for querying and creating projects and jobsets.

Installation

Use nix-env to install:

nix-env -f https://github.com/nlewo/hydra-cli/archive/master.tar.gz -iA hydra-cli

Build

Inside the provided nix shell:

$ cargo build

Usage

hydra-cli talks to the JSON API of hydra and allows you to query, create and wait for projects and jobsets:

project-create Creates a project.
project-list Lists existing projects.
project-show Shows the projects' information.
jobset-create Creates a jobset in a project.
jobset-wait Waits for a jobset's completion.
reproduce Retrieves information for reproducing an output path.
search Searches for an output path.

By default hydra-cli talks to https://hydra.nixos.org. The default can be overwritten by setting the HYDRA_HOST environment variable or by passing --host <host> on the command line.

Commands

$ hydra-cli --help

hydra-cli 0.3.0
lewo
CLI Hydra client

USAGE:
    hydra-cli [FLAGS] [OPTIONS] [SUBCOMMAND]

FLAGS:
    -h, --help                    Prints help information
        --no-check-certificate    Disable TLS certificate check for the Hydra host
    -V, --version                 Prints version information

OPTIONS:
    -H, --host <host>    Hydra host URL [env: HYDRA_HOST=]  [default: https://hydra.nixos.org]

SUBCOMMANDS:
    help              Prints this message or the help of the given subcommand(s)
    jobset-create     Add a jobset to a project
    jobset-eval       Evaluate a jobset
    jobset-wait       Wait for jobset completion
    project-create    Create a new project
    project-list      List projects
    project-show      Get information of a project
    reproduce         Retrieve information to reproduce an output path
    search            Search by output paths

A client to query Hydra through its JSON API.

project-create

The project-create command creates a new project under the name specified. The created project will be enabled and visible. Note: this command requires user authentication.

$ hydra-cli project-create --help

hydra-cli-project-create 
Create a new project

USAGE:
    hydra-cli project-create <project> --password <password> --user <user>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
        --password <password>    A user password [env: HYDRA_PASSWORD=]
        --user <user>            A user name [env: HYDRA_USER=]

ARGS:
    <project>    The name of the project in which to create the jobset

project-list

The project-list command retrieves a list of all configured projects.

$ hydra-cli project-list --help

hydra-cli-project-list 
List projects

USAGE:
    hydra-cli project-list [FLAGS]

FLAGS:
    -h, --help       Prints help information
    -j               JSON output
    -V, --version    Prints version information

project-show

The project-show command displays information on a given project.

$ hydra-cli project-show --help

hydra-cli-project-show 
Get information of a project

USAGE:
    hydra-cli project-show [FLAGS] <project>

FLAGS:
    -h, --help       Prints help information
    -j               JSON output
    -V, --version    Prints version information

ARGS:
    <project>    A project name

jobset-create

The jobset-create command creates a new jobset and adds it to the project specified.

$ hydra-cli jobset-create --help

hydra-cli-jobset-create 
Add a jobset to a project

USAGE:
    hydra-cli jobset-create <project> <jobset> <config> --password <password> --user <user>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
        --password <password>    A user password [env: HYDRA_PASSWORD=]
        --user <user>            A user name [env: HYDRA_USER=]

ARGS:
    <project>    The project to add the jobset to
    <jobset>     The name of the jobset to create
    <config>     Project configuration JSON filepath

Here is an example JSON config:

{
  "description": "hydra-cli master jobset",
  "checkinterval": 60,
  "enabled": 1,
  "visible": true,
  "keepnr": 3,
  "nixexprinput": "src",
  "nixexprpath": "default.nix",
  "inputs": {
    "src": {
      "value": "https://github.com/nlewo/hydra-cli.git master",
      "type": "git",
      "revision": null,
      "uri": null
    }
  }
}

jobset-eval

The jobset-eval command starts the evaluation of a jobset.

$ hydra-cli jobset-eval --help

hydra-cli-jobset-eval 
Evaluate a jobset

USAGE:
    hydra-cli jobset-eval <project> <jobset>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

ARGS:
    <project>    The project to evaluate the jobset from
    <jobset>     The jobset to evaluate

jobset-wait

The jobset-create command waits until the specified jobset has been evaluated.

$ hydra-cli jobset-wait --help

hydra-cli-jobset-wait 
Wait for jobset completion

USAGE:
    hydra-cli jobset-wait [OPTIONS] <project> <jobset>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
        --timeout <timeout>    Maximum time to wait for (in seconds and infinite by default)

ARGS:
    <project>    The project of the jobset to wait for
    <jobset>     The name of the jobset to wait for

reproduce

The reproduce command retrieves information on how to reproduce a given output-path.

$ hydra-cli reproduce --help

hydra-cli-reproduce 
Retrieve information to reproduce an output path

USAGE:
    hydra-cli reproduce [FLAGS] <query>

FLAGS:
    -h, --help       Prints help information
    -j               JSON output
    -V, --version    Prints version information

ARGS:
    <query>    Piece of an output path (hash, name,...)

search

The search command searches for a jobset based on the output-path specified.

$ hydra-cli search --help

hydra-cli-search 
Search by output paths

USAGE:
    hydra-cli search <query> [limit]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

ARGS:
    <query>    Piece of an output path (hash, name,...)
    <limit>    How many results to return [default: 10]

Contributing

Contributions to the project are welcome in the form of GitHub PRs. Please consider the following guidelines before creating PRs:

Please make sure to format your code using rustfmt
If you are planning to make any considerable changes, you should first present your plans in a GitHub issue so it can be discussed.
If you are adding features please consider the possibility of adding a test in tests/vm.nix

Updating the README

hydra-cli uses mdsh to create and verify the README.md you are looking at. Changes to the hydra-cli command syntax will failing tests on hydra.

You can execute the tests locally by running:

nix-build -A tests.readme

If you want to update the README.md after having made relevant changes to hydra-cli you can do so as follows:

cp $(nix-build -A readme) ./README.md

License

Licensed under MIT.
The hydra-cli logo has been created using https://game-icons.net.

nlewo / hydra-cli