Validibot CLI

A command-line interface for Validibot - your automated data validation assistant.

What's Validibot CLI? Validibot CLI is a small library that provides a command line access to Validibot. What's Validibot? So happy you asked! Read more here >> https://validibot.com

Features

• Run validations from the command line or CI/CD pipelines
• Workflow support - reference workflows by ID or human-readable slug
• Organization filtering - disambiguate workflows across orgs and projects
• Secure credential storage - uses system keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service)
• CI/CD friendly - meaningful exit codes and JSON output for scripting

Installation

# Using pip
pip install validibot-cli

# Using uv (recommended)
uv tool install validibot-cli

# Using pipx
pipx install validibot-cli

Requirements

• Python 3.10 or later

Quick Start

1. Authenticate

Get your API key from the Validibot web app, then:

validibot login
# Enter your API key when prompted (input is hidden)

Your API key is stored securely in your system keyring.

2. List Available Workflows

validibot workflows list

This displays a table of workflows you have access to, including their IDs, names, and status.

3. Run a Validation

# By workflow ID
validibot validate model.idf --workflow 123

# By workflow slug
validibot validate model.idf --workflow energyplus-schema-check

The CLI uploads your file, runs the validation workflow, and displays results when complete.

Commands

Authentication

validibot login              # Authenticate with your API key
validibot logout             # Remove stored credentials
validibot whoami             # Show current user info (verifies API key)
validibot auth status        # Check if authenticated (no API call)

Login flow:

1. Prompts for your API key (input is hidden for security)
2. Validates the key against the Validibot API
3. Stores the key securely in your system keyring
4. Fetches your organizations and sets a default:
   • If you belong to one org, it becomes your default automatically
   • If you belong to multiple orgs, you'll be prompted to select one (or skip)
5. Displays your account info to confirm success

Credential storage:

The CLI uses your system's secure credential storage:

• macOS: Keychain
• Windows: Credential Manager
• Linux: Secret Service (GNOME Keyring, KWallet, etc.)

If the system keyring is unavailable, credentials fall back to ~/.config/validibot/credentials.json with restrictive file permissions (owner read/write only). Tokens are stored per API host (based on VALIDIBOT_API_URL).

Workflows

validibot workflows list          # List all available workflows
validibot workflows list --json   # Output as JSON
validibot workflows show <workflow-id-or-slug>  # Show details of a specific workflow

Runs

validibot runs show <run-id>        # Show run status and results
validibot runs show <run-id> --json # Output as JSON

Validation

Basic Usage

# Run a validation (waits for completion by default)
validibot validate model.idf -w <workflow-id-or-slug>

# Run without waiting (returns immediately with run ID)
validibot validate model.idf -w <workflow-id-or-slug> --no-wait

# Check status of a validation run
validibot runs show <run-id>

Workflow Selection

Workflows can be specified by ID (numeric) or slug (human-readable string).

# By numeric ID
validibot validate model.idf -w 123

# By slug
validibot validate model.idf -w energyplus-schema-check

When using slugs, if multiple workflows share the same slug across different organizations or versions, you'll need to disambiguate:

# Specify organization
validibot validate model.idf -w my-workflow --org acme-corp

# Specify organization and project
validibot validate model.idf -w my-workflow --org acme-corp --project building-a

# Specify a particular version
validibot validate model.idf -w my-workflow --org acme-corp --version 2

If the workflow slug is ambiguous, the CLI will display the matching workflows and prompt you to use filtering options.

Output Options

# Verbose output (shows individual step results)
validibot validate model.idf -w <workflow-id-or-slug> --verbose

# JSON output (for scripting/CI)
validibot validate model.idf -w <workflow-id-or-slug> --json

# Custom timeout (default: 600 seconds)
validibot validate model.idf -w <workflow-id-or-slug> --timeout 300

# Name your validation run
validibot validate model.idf -w <workflow-id-or-slug> --name "nightly-build-check"

Full Option Reference

Option	Short	Description
--workflow	-w	Workflow ID or slug (required)
--org	-o	Organization slug (uses default if set)
--project	-p	Project slug for filtering
--version		Workflow version for disambiguation
--name	-n	Name for this validation run
--wait/--no-wait		Wait for completion (default: wait)
--timeout	-t	Max wait time in seconds (default: 600)
--verbose	-v	Show detailed step-by-step output
--json	-j	Output results as JSON

Configuration

Environment Variables

Variable	Description	Default
VALIDIBOT_API_URL	API base URL	https://validibot.com
VALIDIBOT_TOKEN	API key (alternative to validibot login)	-
VALIDIBOT_ORG	Default organization slug	-
VALIDIBOT_TIMEOUT	Request timeout in seconds	300
VALIDIBOT_POLL_INTERVAL	Status polling interval in seconds	5
VALIDIBOT_NO_KEYRING	Disable keyring, use file storage	false
VALIDIBOT_ALLOW_INSECURE_API_URL	Allow non-HTTPS API base URL (dangerous)	false

Using Environment Variables for CI/CD

Instead of running validibot login, you can set VALIDIBOT_TOKEN directly:

export VALIDIBOT_TOKEN="your-api-key"
export VALIDIBOT_ORG="my-org"
validibot validate model.idf -w my-workflow

Organization Resolution

When --org is not explicitly provided, the CLI resolves the organization in this order:

1. --org flag (if provided)
2. VALIDIBOT_ORG environment variable
3. Default org saved during validibot login
4. Error with a helpful message

Exit Codes

The validate command returns meaningful exit codes for CI/CD integration:

Code	Meaning
0	Validation passed
1	Validation failed (FAIL) or CLI/API error
2	Validation error (ERROR/TIMED_OUT/CANCELED/UNKNOWN)
3	Timed out waiting for completion (run still in progress)
130	Interrupted (Ctrl+C)

CI/CD Integration

GitHub Actions

name: Validate Building Model

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install Validibot CLI
        run: pip install validibot-cli

      - name: Validate model
        env:
          VALIDIBOT_TOKEN: ${{ secrets.VALIDIBOT_TOKEN }}
        run: validibot validate model.idf -w ${{ vars.WORKFLOW_ID }}

GitLab CI

validate:
  image: python:3.12
  script:
    - pip install validibot-cli
    - validibot validate model.idf -w $WORKFLOW_ID
  variables:
    VALIDIBOT_TOKEN: $VALIDIBOT_TOKEN

Azure Pipelines

- task: UsePythonVersion@0
  inputs:
    versionSpec: "3.12"

- script: |
    pip install validibot-cli
    validibot validate model.idf -w $(WORKFLOW_ID)
  env:
    VALIDIBOT_TOKEN: $(VALIDIBOT_TOKEN)

Development

# Clone the repository
git clone https://github.com/validibot/validibot-cli.git
cd validibot-cli

# Install with dev dependencies
uv sync --extra dev

# Run the CLI locally
uv run validibot --help

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=validibot_cli

# Lint and format
uv run ruff check .
uv run ruff format .

# Type checking
uv run mypy src/

License

This CLI is open source under the MIT License - see LICENSE for details.

Note: This is an open-source client for the Validibot service. The Validibot platform itself is a commercial product with separate terms of service.