Skip to content

QUICKSTART-CLI-VALIDATION.md

Latest commit

 

History

History
238 lines (174 loc) · 6 KB

QUICKSTART-CLI-VALIDATION.md

File metadata and controls

238 lines (174 loc) · 6 KB

CLI Command Linter - Quick Start

ConfigHub CLI Reference: For authoritative command documentation, use CONFIGHUB_AGENT=1 cub --help-overview or see docs.confighub.com.

Get quick feedback on ConfigHub CLI commands in your project.

⚠️ Important: This is a linter that provides helpful hints for common errors. It is not comprehensive validation. Always test with the actual cub CLI before deploying. See LIMITATIONS.md for what this tool cannot do.

One-Line Validation

curl -fsSL https://raw.githubusercontent.com/monadic/devops-sdk/main/cub-command-analyzer.sh | bash -s -- .

This will:

  1. Download the validator
  2. Scan all shell scripts in current directory
  3. Report any invalid cub commands
  4. Exit with code 0 (valid) or 1 (invalid)

What Gets Validated

✅ Command syntax - Entity + verb structure ✅ Required flags - All mandatory flags present ✅ WHERE clauses - EBNF grammar compliance ✅ Common errors - Inline JSON, missing --space, invalid operators ✅ Semantic correctness - Pre/post conditions

Example Output

Valid commands:

[PASS] All commands are valid!

Summary:
Files analyzed:       12
Commands found:       45
Valid commands:       45
Invalid commands:     0

Invalid commands:

FILE: bin/deploy.sh
LINE 42: cub unit update backend --patch '{"spec":{"replicas":3}}'

SYNTAX VALIDATION:
  [FAIL] Invalid syntax
  Error: --patch requires one of: --from-stdin, --filename, --restore...

COMMON ERRORS:
  - Inline JSON with --patch is invalid
  - Missing required --space flag

SUGGESTED FIXES:
  For DATA update:
    echo '{"spec":{"replicas":3}}' | cub unit update --space dev backend -
  For METADATA update:
    echo '{"Labels":{"version":"1.0"}}' | cub unit update --patch --space dev backend --from-stdin

Installation Options

Option 1: One-Line (No Installation)

# Validate current directory
curl -fsSL https://raw.githubusercontent.com/monadic/devops-sdk/main/cub-command-analyzer.sh | bash -s -- .

# Validate specific directory
curl -fsSL https://raw.githubusercontent.com/monadic/devops-sdk/main/cub-command-analyzer.sh | bash -s -- /path/to/project

Option 2: Clone Repository

# Clone SDK
git clone https://github.com/monadic/devops-sdk.git
cd devops-sdk

# Validate any project
./cub-command-analyzer.sh /path/to/your/project

Option 3: Use Enforcement Script

# Clone SDK
git clone https://github.com/monadic/devops-sdk.git
cd devops-sdk

# Use enforcement script with better output
./bin/validate-cli /path/to/your/project

# CI mode (no colors)
./bin/validate-cli --ci /path/to/your/project

Add to Your Workflow

Pre-Commit Hook

# Copy hook to your project
cp devops-sdk/hooks/pre-commit .git/hooks/
chmod +x .git/hooks/pre-commit

Now all commits are automatically validated!

GitHub Actions

Create .github/workflows/validate-cli.yml:

name: Validate CLI Commands

on: [push, pull_request]

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

      - name: Validate ConfigHub commands
        run: |
          curl -fsSL https://raw.githubusercontent.com/monadic/devops-sdk/main/cub-command-analyzer.sh \
            -o cub-command-analyzer.sh
          chmod +x cub-command-analyzer.sh
          ./cub-command-analyzer.sh .

CI/CD Integration

# In your CI pipeline
curl -fsSL https://raw.githubusercontent.com/monadic/devops-sdk/main/cub-command-analyzer.sh | bash -s -- .

# Check exit code
if [ $? -eq 0 ]; then
    echo "✅ All commands valid"
else
    echo "❌ Invalid commands found"
    exit 1
fi

How Is This Linter Tested?

Testing approach (with honest limitations):

  1. ✅ 39/39 unit tests passing - Validates known patterns (as of 2025-10-12)
  2. ✅ Integration tests - Compared against real cub CLI behavior
  3. ✅ Production testing - 154+ commands validated across 3 projects
  4. ✅ Maintainer feedback - Based on Brian Grant's guidance
  5. ⚠️ Known gaps - May miss newer CLI features

Validation results (point-in-time):

  • TraderX: 88/88 commands valid (2025-10-12)
  • MicroTraderX: 66/66 commands valid (2025-10-12)
  • DevOps Examples: 100% validated (2025-10-12)

Important: These results show the linter works for commands as of the sync date. It may be outdated for newer CLI versions.

See Testing & Verification and LIMITATIONS.md for honest assessment.

Common Errors Fixed

Error 1: Inline JSON with --patch

❌ Wrong:

cub unit update backend --patch '{"spec":{"replicas":3}}'

✅ Correct (DATA update):

echo '{"spec":{"replicas":3}}' | cub unit update --space dev backend -

✅ Correct (METADATA update):

echo '{"Labels":{"version":"1.0"}}' | cub unit update --patch --space dev backend --from-stdin

Error 2: Missing --space Flag

❌ Wrong:

cub unit apply backend

✅ Correct:

cub unit apply backend --space dev

Error 3: Invalid WHERE Clause

❌ Wrong:

cub unit list --where "Slug = 'a' OR Slug = 'b'"  # OR not supported

✅ Correct:

cub unit list --unit a,b  # Use comma-separated names

Error 4: Querying Data Fields

❌ Wrong:

cub unit list --where "Data.spec.replicas > 3"  # Data is opaque

✅ Correct:

# Data fields cannot be queried in WHERE clauses
# Use metadata fields instead: Slug, Labels, Annotations, etc.
cub unit list --where "Labels.tier = 'critical'"

Need Help?

Exit Codes

  • 0 - All commands valid ✅
  • 1 - Invalid commands found ❌
  • 2 - Validation error (missing tools, etc.) ⚠️

Use these in CI/CD to fail builds on invalid commands.