CLI Reference

Complete reference for the labhit command-line tool.

Global Options#

--verbose, -v     Enable debug-level logging
--config, -c      Path to engine config (default: .labhit/config.yaml)
--help, -h        Show help
--version, -V     Show version

Pipeline Commands#

labhit run#

Execute a pipeline.

labhit run [OPTIONS]

Options:

When --file is omitted, LabHit resolves the pipeline file in order: root .labhit.yaml, then .labhit.yml, then .labhit/pipeline.yaml.

Examples:

labhit run                              # Run full pipeline
labhit run --stage build                # Run build + its dependencies
labhit run --dry-run                    # Preview the execution DAG
labhit run -f ci/release-pipeline.yaml  # Use a custom pipeline file

Behavior:

1. Parses pipeline YAML and builds the dependency graph
2. Detects Docker availability for sandbox: stages
3. Loads extensions from .labhit/extensions/
4. Loads policies from .labhit/policies/ (if present)
5. Dispatches stages in parallel where dependencies allow
6. Prints colored status for each stage
7. Exits with code 0 on success, 1 on failure

labhit validate#

Validate pipeline YAML without executing.

labhit validate [OPTIONS]

Options:

When --file is omitted, the same resolution order applies as for labhit run: root .labhit.yaml, then .labhit.yml, then .labhit/pipeline.yaml.

Checks:

• YAML syntax
• Required fields (engine, pipeline.name, stages)
• Stage structure (each stage has use: or run:, not both)
• Dependency graph (no cycles, no missing stage references)

Examples:

labhit validate
labhit validate --file custom-pipeline.yaml

labhit init#

Scaffold a new LabHit project.

labhit init [PATH]

Arguments:

Creates:

• .labhit.yaml: Starter pipeline template (in the project root)
• .labhit/config.yaml: Engine configuration template (optional)

Examples:

labhit init                   # Initialize current directory
labhit init ./my-project      # Initialize a new directory

Server Commands#

labhit serve#

Start the LabHit API server.

labhit serve [OPTIONS]

Options:

Environment variables:

Examples:

labhit serve                                    # Local dev server
labhit serve --port 3000 --playground           # With GraphQL playground
labhit serve --format json --database-url sqlite:///var/lib/labhit/data.db

Authentication Commands#

labhit auth login#

Authenticate via GitHub.

labhit auth login [OPTIONS]

Options:

Flow:

1. Requests a device code from the API server
2. Opens your browser to GitHub's authorization page
3. Displays a user code to enter on GitHub
4. Polls until authorization completes
5. Stores tokens at ~/.labhit/credentials.json (file mode 0600)

labhit auth status#

Show current authentication status.

labhit auth status

Output includes: email, tier, API URL, credentials file path.

labhit auth logout#

Revoke session and remove local credentials.

labhit auth logout

Sends the refresh token to the API to revoke the session server-side, then deletes ~/.labhit/credentials.json.

labhit auth refresh#

Refresh an expired access token.

labhit auth refresh

Uses the stored refresh token to obtain a new access token without re-authenticating.

Extension Commands#

labhit extension init#

Scaffold a new extension project.

labhit extension init <NAME> [OPTIONS]

Arguments:

Options:

Creates:

• Cargo.toml with labhit-pdk dependency
• src/main.rs with extension entry point template
• extension.yaml manifest with metadata and capabilities

Examples:

labhit extension init scan/my-scanner
labhit extension init build/custom-builder --lang rust

labhit extension build#

Compile an extension to WASM.

labhit extension build [PATH]

Arguments:

Requirements:

• wasm32-wasip1 target installed: rustup target add wasm32-wasip1
• Cargo.toml with labhit-pdk dependency

Output: target/wasm32-wasip1/release/<crate_name>.wasm

labhit extension test#

Test an extension locally.

labhit extension test [PATH]

Builds the extension, loads it in the WASM runtime with a sample StepInput, and displays the output, metadata, and logs.

labhit extension list#

List installed extensions.

labhit extension list

Shows extensions in .labhit/extensions/ with their ID, name, version, and capability count.

Output format:

ID                    NAME             VERSION   CAPABILITIES
scan/my-scanner       My Scanner       0.1.0     3
source/git            Git Source        1.0.0     2

labhit extension install

Install an extension from a package file.

labhit extension install <ID> [OPTIONS]

Arguments:

Options:

Examples:

labhit extension install source/git
labhit extension install scan/trivy --version 0.5.0

Validates the package, extracts it to .labhit/extensions/<category>/<name>/.

labhit extension pack#

Package an extension for distribution.

labhit extension pack [PATH] [OPTIONS]

Options:

Builds the extension, creates a .lhx package (compressed archive containing the WASM module, manifest, and README), and prints the file size and SHA-256 hash.

Output: <name>-<version>.lhx

labhit extension search

Search the extension registry.

labhit extension search <QUERY> [OPTIONS]

Options:

Examples:

labhit extension search trivy
labhit extension search scanner --category scan

Secrets Commands#

Manage server-side, per-repository encrypted secrets. Secrets are stored encrypted on the server and made available to pipeline runs for the owning repository. Secret values are never printed back.

labhit secrets set#

Set or update a secret for a repository.

labhit secrets set <OWNER/REPO> <KEY>

Arguments:

The secret value is not passed as a command-line argument (keeping it out of shell history); it is stored encrypted on the server.

Examples:

labhit secrets set my-org/my-app NPM_TOKEN
labhit secrets set my-org/my-app DEPLOY_KEY

labhit secrets list#

List the secret names configured for a repository.

labhit secrets list <OWNER/REPO>

Prints only secret names and metadata. Secret values are never displayed.

labhit secrets remove#

Remove a secret from a repository.

labhit secrets remove <OWNER/REPO> <KEY>

Exit Codes#

Configuration Files#