Plugin-first CLI architecture with clio as the foundational manager
This is a production-ready monorepo containing a unified CLI (clio) with pluggable functionality built with:
- oclif - Extensible CLI framework with plugin system
- TypeScript - Type-safe development
- pnpm - Fast, efficient package manager
- Turborepo - Intelligent build system with caching
- Changesets - Automated versioning and changelogs
# Install clio with default task management plugin
npm install -g @cli-ops/clio
# Or install persona-based bundles
npm install -g @cli-ops/clio-meta-developer # clio + fetch + repo
npm install -g @cli-ops/clio-meta-complete # all plugins# Install additional plugins as needed
clio plugins:install @cli-ops/clio-plugin-fetch
clio plugins:install @cli-ops/clio-plugin-repoclio config:get KEY # Get configuration value
clio config:set KEY VALUE # Set configuration value
clio history:list # View command history
clio doctor # Check installation health
clio plugins # Manage pluginsclio tasks:create "Task" # Create a new task
clio tasks:list # List all tasks
clio tasks:update ID # Update a task
clio tasks:delete ID # Delete a taskclio fetch:get URL # Make HTTP GET request
clio fetch:post URL # Make HTTP POST request
clio auth:login # Authenticateclio repo:status # Show repository status
clio repo:clone REPO # Clone a repository
clio repo:pr # Manage pull requests.
├── apps/
│ ├── clio/ # Core CLI manager
│ └── website/ # Documentation site
├── plugins/
│ ├── clio-plugin-tasks/ # Task management (bundled)
│ │ └── src/
│ │ └── extensions/ # Extensions that enhance tasks plugin
│ │ └── clio-plugin-tasks-jira/ # Jira integration
│ ├── clio-plugin-fetch/ # HTTP API client
│ │ └── src/
│ │ └── extensions/ # Extensions that enhance fetch plugin
│ │ └── clio-plugin-fetch-oauth/ # OAuth authentication
│ └── clio-plugin-repo/ # Developer tools
│ └── src/
│ └── extensions/ # Extensions that enhance repo plugin
│ └── clio-plugin-repo-hooks/ # Git hooks automation
├── libs/
│ ├── clio-meta-*/ # Persona-based bundles
│ └── shared-*/ # Shared libraries (@cli-ops/shared-*)
├── tooling/ # Development configs
├── docs/ # Documentation
└── scripts/ # Helper scripts
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Run CLIs in dev mode
pnpm dev:clio # Core CLI
pnpm dev:tasks # Tasks plugin
pnpm dev:fetch # Fetch plugin
pnpm dev:repo # Repo plugin
pnpm dev:docs # Documentation site
# Generate new code
pnpm generate:plugin # Create new plugin with full setup
pnpm generate:command # Add command to existing plugin
pnpm generate:package # Create new shared package
# Run tests
pnpm test
# Lint & format
pnpm lint
pnpm format
# Type check
pnpm typecheck
# Clean build artifacts
pnpm cleanUse the generator to scaffold a new plugin:
pnpm generate:plugin
# Follow the prompts:
# - Plugin name (e.g., "slack")
# - Description
# - Author
# - Include tests? (Y/n)
# - Include CI? (Y/n)
# - Include docs? (Y/n)This creates a complete plugin with:
- TypeScript setup
- Command templates
- Test structure
- CI/CD workflow (optional)
- Documentation template (optional)
- oclif configuration
All packages use @cli-ops scoped names:
- Core:
@cli-ops/clio - Plugins:
@cli-ops/clio-plugin-{name} - Extensions:
@cli-ops/{plugin}-plugin-{feature} - Shared:
@cli-ops/shared-{name} - Meta:
@cli-ops/clio-meta-{persona}
Import using @/ aliases:
import { logger } from '@/shared-logger'
import { BaseCommand } from '@/shared-commands'- Plugin-first design: Core CLI + pluggable functionality
- Independent versioning: Each package versioned separately
- Persona-based bundles: Install what you need
- Shared infrastructure: Common utilities across plugins
- NPM published: Available via
@cli-opsorganization
- Budget:
<500msfor help commands,<200msfor version - Shell Completion: Auto-generated for bash/zsh/fish
- Consistency: Enforced via ESLint, Prettier, git hooks
- Testing: Unit + E2E tests with coverage requirements
See docs/ for detailed documentation:
Automated via GitHub Actions and Changesets with npm trusted publishing (OIDC).
# Create a changeset
pnpm changeset
# Version packages (in CI)
pnpm changeset:version
# Publish to npm (in CI)
pnpm changeset:publishThe release workflow uses npm Trusted Publishing for secure, token-less authentication:
- OIDC Authentication: No long-lived npm tokens required
- See NPM Trusted Publishing Guide
- Automatic provenance attestation
- Enhanced supply chain security
- Industry-standard approach
Note: Due to GitHub Actions restrictions on PR creation, the release workflow requires a Personal Access Token (PAT) for creating version PRs. See the Release Process documentation for setup instructions.
BREAKING CHANGES: Extension plugins refactored to top-level architecture
- ✨ Extensions moved from nested to top-level
plugins/directories - ✨ New
BaseExtensionPluginclass with explicit parent registration - ✨ Type-safe hook system for extension points (replaces event-only approach)
- ✨ Runtime validation of parent dependencies and hook compatibility
- ✨
clio plugins:extensionscommand for extension discovery - ✨
pnpm validate:extensionsscript for automated validation - 📚 Extension API documentation added to all base plugin READMEs
- 🔄 Backward compatible: Event-based communication still supported
Migration Required: See ADR-010 for upgrade guide
Affected Packages:
@cli-ops/shared-plugins@4.0.0@cli-ops/clio-plugin-tasks@4.0.0@cli-ops/clio-plugin-fetch@4.0.0@cli-ops/clio-plugin-repo@4.0.0@cli-ops/clio-plugin-tasks-jira@4.0.0@cli-ops/clio-plugin-fetch-oauth@4.0.0@cli-ops/clio-plugin-repo-hooks@4.0.0
Note: This is the initial stable release of all packages, incorporating the extension plugin formalization work.
- 🚀 Plugin-first architecture with clio as the foundational manager
- 📦 oclif v4 with plugin management
- 📝 Command history with undo/redo support
- ⚙️ Unified configuration management
- 🔧 Built-in task management (bundled with clio)
- 🔌 Event-based inter-plugin communication
- 📚 Comprehensive documentation and testing utilities
MIT