Zondax CLI

A comprehensive CLI tool for Zondax development workflows, featuring infrastructure management, CI/CD integration, and TypeScript refactoring tools.

Installation

npm install -g @zondax/cli
# or
npx @zondax/cli@latest

Commands

Infrastructure Management (infra)

• cloudsql - Cloud SQL Proxy management
• devpod - Development pod management
• kubeconfig - Kubernetes configuration management
• images - Container image management
• onboard - Developer onboarding tools

CI/CD Integration (ci)

• checkout - GitHub App authentication and checkout
• git - Git best practices checks (file sizes, denied types)

Environment Management (env)

• Environment variable management using GCP Secret Manager

Model Context Protocol (mcp)

• proxy - MCP proxy for bridging stdio and HTTP MCP servers

Source Management (vendor)

• Manage external source dependencies and vendored code

Version Management (version)

• Unified version management across multiple files in monorepos
• Supports package.json, Cargo.toml, and tauri.conf.json
• Configuration-driven with glob pattern support

Version Management

Manage versions across multiple files in your project with a single command. Perfect for monorepos where you need to keep versions synchronized across packages, apps, and configuration files.

Quick Start

# Initialize configuration in your project
npx @zondax/cli@latest version init

# Check current version
npx @zondax/cli@latest version get

# Check consistency across all files
npx @zondax/cli@latest version check

# Bump patch version (1.2.3 → 1.2.4)
npx @zondax/cli@latest version bump patch

# Set specific version
npx @zondax/cli@latest version set 2.0.0

Commands

version init - Generate .zondaxrc.json configuration

• Auto-detects common version files in your project
• Creates configuration with sensible defaults
• Use --force to overwrite existing configuration

version get - Display current version

• Shows version from primary file (typically root package.json)

version check - Verify consistency

• Checks all configured files have the same version
• Displays which files have which versions
• Exits with error code if inconsistent

version set <version> - Set specific version

• Updates all configured files to the specified version
• Validates semantic versioning format
• Warns on downgrades with confirmation prompt
• Use --dry-run to preview changes
• Use --yes to skip confirmations (for CI/CD)

version bump <type> - Increment version

• Types: patch, minor, major
• Automatically calculates new version
• Updates all configured files atomically
• Use --dry-run to preview changes
• Use --yes to skip confirmations

Configuration

The .zondaxrc.json file configures which files to manage:

{
  "version": {
    "files": [
      "package.json",
      "apps/*/package.json",
      "packages/*/package.json",
      "apps/tauri/src-tauri/Cargo.toml",
      "apps/tauri/src-tauri/tauri.conf.json"
    ],
    "allowDevVersions": true,
    "allowDowngrade": false
  }
}

Options:

• files - Array of file paths or glob patterns
• allowDevVersions - Accept dev build versions (default: true)
• allowDowngrade - Allow downgrades without confirmation (default: false)

Supported File Types

The tool automatically detects and handles:

• package.json - Node.js packages
• Cargo.toml - Rust projects
• tauri.conf.json - Tauri applications

Glob Patterns

Use glob patterns for flexible file matching:

{
  "files": [
    "package.json",           // Single file
    "apps/*/package.json",    // All apps
    "packages/*/package.json" // All packages
  ]
}

Examples

Monorepo setup:

# Initialize
npx @zondax/cli@latest version init

# Preview patch bump
npx @zondax/cli@latest version bump patch --dry-run

# Apply the bump
npx @zondax/cli@latest version bump patch

# Verify all files updated
npx @zondax/cli@latest version check

CI/CD workflow:

# Automated version bump in CI
npx @zondax/cli@latest version bump minor --yes

Set pre-release version:

npx @zondax/cli@latest version set 2.0.0-beta.1

Dev Build Versions

The tool supports dev build version patterns:

• Old: 0.0.0-dev.20231201 or 0.0.0-dev20231201
• New: 1.2.3-dev.5.abc1234

These are treated specially and don't trigger downgrade warnings.

MCP Proxy

The MCP proxy bridges stdio-based MCP clients with HTTP-based MCP servers, enabling you to use HTTP MCP servers with tools like Claude Code that expect stdio communication.

Proxy Usage

# Basic usage - proxy to an HTTP MCP server
npx @zondax/cli@latest mcp proxy --url http://localhost:8000/mcp/

# With authentication headers
npx @zondax/cli@latest mcp proxy --url http://localhost:8000/mcp/ --header "Authorization: Bearer YOUR_TOKEN"

# With custom timeout and verbose logging
npx @zondax/cli@latest mcp proxy --url http://localhost:8000/mcp/ --timeout 60000 --verbose

# Multiple headers
npx @zondax/cli@latest mcp proxy --url http://localhost:8000/mcp/ \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "X-API-Key: YOUR_API_KEY"

Proxy Options

• --url, -u: HTTP MCP server URL (required)
• --verbose, -v: Enable verbose logging for debugging
• --timeout, -t: Request timeout in milliseconds (default: 30000)
• --header, -H: Add custom headers (can be used multiple times)

Claude Code Integration with HTTP MCP Servers

# Add HTTP MCP server via proxy
claude mcp add my-http-server npx @zondax/cli@latest mcp proxy --url http://localhost:8000/mcp/

# With authentication
claude mcp add my-http-server npx @zondax/cli@latest mcp proxy \
  --url http://localhost:8000/mcp/ \
  --header "Authorization: Bearer YOUR_TOKEN"

CI Git Checks

The ci git command helps maintain repository best practices by checking for large files and denied file types.

Git Check Usage

# Basic check with defaults (no configuration needed!)
npx @zondax/cli@latest ci git

# Fail on warnings as well as errors
npx @zondax/cli@latest ci git --strict

# Override size limits
npx @zondax/cli@latest ci git --max-size 5 --warn-size 2

# Use custom configuration file (if not in default location)
npx @zondax/cli@latest ci git --config custom/my-gitcheck.yaml

Default Checks

File Size Limits:

• Error: Files larger than 1.0 MB
• Warning: Files larger than 0.5 MB

Denied File Types:

• Video files (mp4, avi, mov, etc.)
• Archives (zip, tar, rar, etc.)
• Large binaries (exe, dmg, iso, etc.)
• Database dumps (sql, dump, bak)
• Design files (psd, ai, sketch, etc.)
• Large audio files (wav, flac, aiff)

Configuration (Optional)

Create a .gitcheck.yaml file to customize settings:

version: 1
sizes:
  max_file_mb: 2.0        # Custom max file size
  warning_file_mb: 1.0    # Custom warning threshold

extensions:
  deny:                   # Override the default deny list
    - "*.mp4"
  ignore:                 # Allow specific extensions
    - "*.woff2"

paths:
  ignore:                 # Ignore files or directories by path
    - "docs/demo.mp4"
    - "assets/fonts/**"

behavior:
  fail_on_warning: false  # Only fail on errors
  fail_on_violation: true # Fail when violations found

GitHub Actions Integration

When running in GitHub Actions, the command automatically:

• Outputs annotations that appear on PR files
• Creates a job summary with detailed results
• Sets output variables for workflow steps
• Groups log output for better readability

Example workflow:

- name: Check Git Best Practices
  run: npx @zondax/cli@latest ci git --strict

Development

Prerequisites

• Node.js 20+
• pnpm 10+
• TypeScript 5.8+

Setup

pnpm install

Testing

pnpm test

Code Quality

pnpm run check    # Format and lint
pnpm run lint     # Lint only
pnpm run format   # Format only

Architecture

The CLI follows a modular command structure:

• src/cmd/ - Command definitions grouped by functionality
• src/lib/ - Shared utilities and libraries
• src/main.ts - Main entry point using Commander.js

Key Libraries

• Commander.js - CLI framework
• @modelcontextprotocol/sdk - MCP server implementation
• Biome - Code formatting and linting
• Vitest - Testing framework

License

UNLICENSED - Proprietary to Zondax AG