CLI¶

The Gradient CLI provides command-line access to all server functionality. It communicates with the same REST API as the web interface.

Installation¶

Via Nix Flake (NixOS)¶

{
  inputs.gradient.url = "github:wavelens/gradient";

  outputs = { self, nixpkgs, gradient, ... }:
  let
    pkgs = import nixpkgs {
      system = "x86_64-linux";
      overlays = [ gradient.overlays.gradient-cli ];
    };
  in {
    nixosConfigurations.yourhostname = pkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        { environment.systemPackages = [ pkgs.gradient-cli ]; }
      ];
    };
  };
}

Run Without Installing¶

nix run github:wavelens/gradient#gradient-cli -- --help

Configuration¶

Before using the CLI, point it at your Gradient server:

gradient config server https://gradient.example.com

Then log in:

gradient login

You will be prompted for your username and password. The token is stored in the local configuration file (~/.config/gradient/config).

Commands¶

Authentication¶

Command	Description
gradient register	Register a new user account
gradient login	Log in and store an auth token
gradient logout	Clear the stored auth token
gradient info	Print current user information
gradient status	Check connectivity to the server

Organizations¶

gradient organization list
gradient organization create
gradient organization delete <name>

Projects¶

gradient project list
gradient project create
gradient project delete <name>
gradient project eval <name>          # Trigger a new evaluation

Build Servers¶

gradient server list
gradient server add
gradient server remove <name>

Caches¶

gradient cache list
gradient cache add
gradient cache remove <name>

Builds¶

# Build a derivation directly (remote build)
gradient build <derivation-path>
gradient build <derivation-path> --organization myorg

# Download build artifacts
gradient download --build-id <uuid>
gradient download --build-id <uuid> --filename output.tar

Utilities¶

# Generate shell completions
gradient completion bash   >> ~/.bashrc
gradient completion zsh    >> ~/.zshrc
gradient completion fish   >> ~/.config/fish/completions/gradient.fish

# Generate project files
gradient generate <type>

Global Options¶

gradient --help      Show help for any command
gradient --version   Print CLI version