Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@zondax/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

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+
Bun 1.1+
TypeScript 5.8+

Setup

bun install

Testing

bun test

Code Quality

bun run check    # Format and lint
bun run lint     # Lint only
bun 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

@zondax/cli