Skip to content

cli-reference.adoc

Latest commit

 

History

History
919 lines (667 loc) · 12.8 KB

cli-reference.adoc

File metadata and controls

919 lines (667 loc) · 12.8 KB
Raw

hypatia CLI Reference

Table of Contents

Overview

The hyper CLI is the command-line interface for the hypatia neurosymbolic CI/CD platform. It combines neural learning with symbolic reasoning to provide intelligent CI/CD automation and issue detection.

Installation

cargo install hypatia-cli

Global Options

Option Short Description Default

--output <FORMAT>

-o

Output format: json, yaml, table, or plain

plain

--verbose

-v

Enable verbose output (use -vv for debug, -vvv for trace)

Off

--quiet

-q

Suppress all non-error output

Off

--config <PATH>

-c

Configuration file path

~/.config/hyper/config.toml

--no-color

Disable colored output

Off

Environment variables:

  • HYPER_OUTPUT: Default output format

  • HYPER_CONFIG: Default configuration file path

  • NO_COLOR: Disable colored output

Commands

scan

Scan a repository for CI/CD issues and policy violations.

Synopsis

hyper scan [OPTIONS] [REPO_PATH]

Arguments

Argument Description Default

REPO_PATH

Path to the repository to scan

. (current directory)

Options

Option Short Description Default

--min-severity <LEVEL>

-s

Minimum severity level to report: info, low, medium/med, high, critical/crit

low

--categories <LIST>

-c

Categories to scan (comma-separated): security, policy, configuration, or all

all

--fixable-only

Include auto-fixable issues only

Off

--detailed

Generate a detailed report with code snippets and documentation links

Off

--report-file <PATH>

Save JSON report to file

None

--skip <LIST>

Skip specific checks (comma-separated check IDs)

None

--include-hidden

Include hidden files in scan

Off

Check IDs

Check ID Category Description Auto-Fixable

unpinned-actions

Security

GitHub Actions not pinned to SHA

Yes

missing-permissions

Security

Workflow missing permissions declaration

Yes

missing-spdx

Policy

Missing SPDX license header

Yes

missing-spdx-source

Policy

Missing SPDX header in source files

Yes

missing-security-policy

Policy

Missing SECURITY.md

Yes

missing-license

Policy

Missing LICENSE file

No

missing-gitignore

Configuration

Missing .gitignore file

No

missing-readme

Documentation

Missing README file

No

missing-contributing

Documentation

Missing CONTRIBUTING guide

No

Examples

# Scan current directory
hyper scan

# Scan with minimum high severity
hyper scan --min-severity high /path/to/repo

# Scan only security issues, output as JSON
hyper scan -c security -o json > report.json

# Scan with detailed report saved to file
hyper scan --detailed --report-file findings.json

# Skip specific checks
hyper scan --skip unpinned-actions,missing-spdx-source

fleet

Run bot fleet operations on a repository. Executes configured bots in dependency order to analyze and fix issues.

Synopsis

hyper fleet <SUBCOMMAND> [OPTIONS]

Subcommands

fleet run

Run bots on a repository.

hyper fleet run [OPTIONS] [REPO_PATH]
Option Short Description Default

--bots <LIST>

-b

Run only these bots (comma-separated)

All bots

--exclude <LIST>

-e

Exclude these bots (comma-separated)

None

--dry-run

-n

Show what would be done without making changes

Off

--parallel

-p

Run independent bots in parallel

Off

--continue-on-error

Continue if a bot fails

Off

--timeout <SECONDS>

Timeout per bot in seconds

300

--auto-fix

Automatically apply fixes

Off

--category <CAT>

Run bots from specific category: security, quality, documentation, compliance, performance, release

All categories
fleet list

List available bots.

hyper fleet list [OPTIONS]
Option Short Description

--category <CAT>

Filter by category
fleet status

Show status of running or completed bot operations.

hyper fleet status [OPTIONS]
Option Short Description

--run-id <ID>

Show status of specific run
fleet stop

Stop running bot operations.

hyper fleet stop [OPTIONS]
Option Short Description

--run-id <ID>

Stop specific run

--all

Stop all running operations

Bot Categories

Category Description

security

Security scanning and vulnerability detection

quality

Code quality and linting

documentation

Documentation generation and validation

compliance

Policy compliance and license checks

performance

Performance analysis and optimization

release

Release automation and changelog generation

Available Bots

Bot ID Category Description Auto-Fix

robot-repo-automaton

Quality

Repository automation and standards enforcement

Yes

glambot

Documentation

Documentation generation and linting

Yes

finishing-bot

Release

Release preparation and changelog

Yes

echidnabot

Security

Secret detection and security scanning

No

seambot

Quality

Code formatting and style

Yes

compliance-bot

Compliance

License and policy compliance

Yes

Examples

# Run all bots on current directory
hyper fleet run

# Run only security bots
hyper fleet run --category security

# Run specific bots with auto-fix
hyper fleet run --bots glambot,seambot --auto-fix

# Dry run to see what would be done
hyper fleet run --dry-run

# Run bots in parallel with timeout
hyper fleet run --parallel --timeout 600

# List available bots
hyper fleet list

# Check status of a run
hyper fleet status --run-id abc123

hooks

Manage git hooks in a repository.

Synopsis

hyper hooks <SUBCOMMAND> [OPTIONS]

Subcommands

hooks install

Install git hooks into a repository.

hyper hooks install [OPTIONS] [REPO_PATH]
Option Short Description Default

--hooks <LIST>

Hooks to install (comma-separated): pre-commit, pre-push, post-receive, commit-msg, prepare-commit-msg, post-commit, post-checkout, post-merge

pre-commit,pre-push

--force

-f

Overwrite existing hooks

Off

--backup

Backup existing hooks before overwriting

Off

--available

Show available hook templates

Off
hooks remove

Remove installed git hooks.

hyper hooks remove [OPTIONS] [REPO_PATH]
Option Short Description

--hooks <LIST>

Hooks to remove (comma-separated)

--yes

-y

Skip confirmation prompt
hooks list

List installed hooks.

hyper hooks list [REPO_PATH]
hooks status

Show status of installed hooks.

hyper hooks status [REPO_PATH]
hooks update

Update installed hooks to latest version.

hyper hooks update [OPTIONS] [REPO_PATH]
Option Short Description

--hooks <LIST>

Specific hooks to update

Hook Types

Hook Description

pre-commit

Runs before commit is created. Blocks banned languages, validates SPDX headers.

pre-push

Runs before push. Validates workflow security, runs lint checks.

commit-msg

Validates commit message format.

prepare-commit-msg

Prepares default commit message.

post-commit

Runs after commit. Updates local indexes.

post-checkout

Runs after checkout. Validates branch policies.

post-merge

Runs after merge. Updates dependencies.

post-receive

Server-side hook for push processing.

Examples

# Install default hooks (pre-commit and pre-push)
hyper hooks install

# Install all hooks with backup
hyper hooks install --hooks pre-commit,pre-push,commit-msg --backup

# Force reinstall, overwriting existing
hyper hooks install --force

# Show available hook templates
hyper hooks install --available

# Remove all installed hooks
hyper hooks remove --yes

# Check hook status
hyper hooks status

deposit

Submit a ruleset to the registry.

Synopsis

hyper deposit [OPTIONS] <RULESET_FILE>

Arguments

Argument Description

RULESET_FILE

Path to the ruleset file (.lgt or .hs)

Options

Option Short Description Default

--registry <URL>

-r

Registry URL

Default registry

--validate-only

Validate without depositing

Off

--force

-f

Force deposit even if version exists

Off

--tag <TAG>

-t

Add tags to the ruleset (comma-separated)

None

Examples

# Deposit a ruleset
hyper deposit my-rules.lgt

# Validate only
hyper deposit --validate-only my-rules.lgt

# Deposit with tags
hyper deposit --tag security,workflow my-rules.lgt

withdraw

Pull a ruleset from the registry.

Synopsis

hyper withdraw [OPTIONS] <RULESET_ID>

Arguments

Argument Description

RULESET_ID

Ruleset ID or name

Options

Option Short Description Default

--registry <URL>

-r

Registry URL

Default registry

--version <VER>

-V

Specific version to withdraw

Latest

--output <PATH>

-o

Output file path

stdout

Examples

# Withdraw latest version
hyper withdraw security-rules

# Withdraw specific version
hyper withdraw --version 1.2.0 security-rules

# Save to file
hyper withdraw -o rules.lgt security-rules

search

Search for rulesets in the registry.

Synopsis

hyper search [OPTIONS] [QUERY]

Options

Option Short Description Default

--registry <URL>

-r

Registry URL

Default registry

--effect <EFFECT>

-e

Filter by effect: preventive, curative, diagnostic

All

--language <LANG>

-l

Filter by target language

All

--category <CAT>

Filter by category

All

--tag <TAG>

-t

Filter by tag

None

--limit <N>

-n

Maximum results

50

Examples

# Search for security rulesets
hyper search security

# Search by effect
hyper search --effect preventive

# Search by language
hyper search --language rust

# Combine filters
hyper search --category security --tag workflow

config

Show or manage configuration.

Subcommands

config show

Show current configuration.

hyper config show
config init

Initialize configuration file.

hyper config init
config set

Set a configuration value.

hyper config set <KEY> <VALUE>
config get

Get a configuration value.

hyper config get <KEY>

Configuration Keys

Key Description Default

registry.url

Registry server URL

https://registry.hypatia.io

registry.token

Authentication token

None

scan.min_severity

Default minimum severity

low

fleet.timeout

Default bot timeout (seconds)

300

fleet.parallel

Run bots in parallel by default

false

hooks.default

Default hooks to install

pre-commit,pre-push

Examples

# Initialize config
hyper config init

# Show current config
hyper config show

# Set registry URL
hyper config set registry.url https://my-registry.example.com

# Get a value
hyper config get registry.url

version

Show version and build information.

hyper version

Output includes:

  • Package name and version

  • Git commit (if built from git)

  • Build date

  • Rust version

  • Target platform

Exit Codes

Code Meaning

0

Success

1

Critical findings detected (scan) or general error

2

Invalid arguments

3

Configuration error

4

Network/registry error

5

Permission denied

Configuration File

The configuration file uses TOML format and is located at ~/.config/hyper/config.toml by default.

# hypatia configuration

[registry]
url = "https://registry.hypatia.io"
# token = "your-token-here"

[scan]
min_severity = "low"
categories = ["all"]
include_hidden = false

[fleet]
timeout = 300
parallel = false
continue_on_error = false

[hooks]
default = ["pre-commit", "pre-push"]
backup = true

[output]
format = "plain"
color = true