Echelon

Consolidated CLI for DodaTech's internal development platform. Replaces per-project Bash tooling with a single globally-installed binary.

Installation

npm install -g @dodatech/echelon

Quick Start

# Initialize in an existing git repo
echelon init

# Start work on a GitHub issue
echelon forge start https://github.com/org/repo/issues/42

# Create a PR when done
echelon forge finish --classification ship

# Check status of all epics
echelon forge status

# Create a release
echelon forge release patch

# Validate setup
echelon doctor

Commands

Forge Workflow

| Command | Description | |---------|-------------| | forge start <issue-url> | Create branch from GitHub issue, push to remote | | forge finish | Create PR with merge classification label | | forge status | Show active epics and PR status | | forge release <patch\|minor\|major> | Semantic version bump, annotated tag, push | | forge handoff | Clean client-ready repo sync |

Project Management

| Command | Description | |---------|-------------| | init | Initialize .echelon/ config in current project | | doctor | Validate project setup and dependencies | | migrate | Migrate config/state from older formats |

Common Flags

• --json — Machine-readable JSON output
• --dry-run — Preview without making changes (where applicable)
• --verbose / -v — Show verbose output

Configuration

Echelon uses .echelon/echelon.yaml for project configuration:

project:
  name: "My Project"

git:
  default_branch: main

forge:
  runtime:
    package_manager: pnpm
    test_command: "pnpm test"

  pr:
    default_classification: ask  # ship | show | ask

  handoff:
    target_repo: "https://github.com/client/repo.git"
    exclude_patterns:
      - "internal-docs/"

See templates/echelon.yaml for a full template with all options.

Authentication

GitHub access uses this cascade (first match wins):

1. GH_TOKEN environment variable
2. GITHUB_TOKEN environment variable
3. gh auth token (GitHub CLI)

Merge Classifications

PRs are labeled with merge intent:

• ship — merge immediately after CI passes
• show — ready for review, merge after approval
• ask — needs discussion before merging

Migration

Coming from .forge/ scripts or an older Echelon setup:

echelon migrate

This converts old config formats and state files to the current schema.

Development

pnpm install
pnpm build
pnpm test
./bin/dev.js <command>

License

Private — DodaTech internal use only.