cli

module
v0.7.0-alpha.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 5, 2026 License: MIT

README

Context Vibes CLI

Go Report Card

Open in Firebase Studio

Context Vibes is a command-line tool designed to streamline common development tasks and generate context for AI assistants. It provides consistent wrappers for Git workflows, Infrastructure as Code (IaC) operations, code quality checks, formatting, testing, and programmatic code modifications, focusing on clear, structured terminal output and detailed background logging.

Why Context Vibes?

  • Consistency: Provides a unified interface and terminal output style for frequent actions (commit, sync, deploy, etc.).
  • Automation: Simplifies multi-step processes and provides non-interactive options via the global --yes flag. Designed for use in scripts or by AI agents.
  • AI Integration:
    • AI-Assisted Workflows: Use the --ai flag on core commands (commit, finish, quality, codemod) to generate optimized prompts for your AI assistant.
    • Context Generation: Generates a contextvibes.md context file (describe, diff) suitable for AI prompts.
    • Strategic Planning: The kickoff --strategic command generates a master prompt to guide an AI-facilitated strategic project kickoff.
    • Traceability: Produces structured terminal output and a detailed JSON trace log (default: contextvibes_ai_trace.log) for deeper AI analysis.
  • Clarity & Safety: Uses distinct output formats and requires confirmation for state-changing operations (unless --yes is specified).
  • Configurability: Supports a .contextvibes.yaml file for customizing default behaviors (Git, validation rules, logging, AI interaction preferences). See the Configuration Reference for details.

Key Features

  • AI Context Generation: describe, diff.
  • Enhanced Git Workflow Automation:
    • kickoff: Starts a new task. Use --strategic for AI-assisted project planning.
    • commit: Stages and commits changes. Use --ai to generate a commit message prompt.
    • finish: Pushes and creates a PR. Use --ai to generate a PR description prompt.
    • sync, status, tidy.
  • Infrastructure as Code (IaC) Wrappers: plan, deploy, init (Terraform/Pulumi).
  • Code Quality & Formatting:
    • quality: Runs static analysis. Use --ai to generate a code review prompt.
    • format: Formats code (Go, Python, Terraform).
  • Code Modification:
    • codemod: Applies programmatic changes. Use --ai to generate a refactoring prompt.
  • Project Testing & Versioning: test, version.

(For detailed information on each command, see the Command Reference.)

Installation

Ensure you have Go (1.24 or later recommended) and Git installed.

  1. Install using go install:

    go install github.com/contextvibes/cli/cmd/contextvibes@latest

    Installs to $GOPATH/bin (usually $HOME/go/bin).

  2. Ensure Installation Directory is in your PATH:

    # Add one of these to your shell profile (.bashrc, .zshrc, etc.)
export PATH=$(go env GOPATH)/bin:$PATH
# Or: export PATH=$HOME/go/bin:$PATH

    Restart your shell or source the profile (source ~/.bashrc).

(Alternative) Installation via Releases: Download from GitHub Releases (Adjust URL when releases are available), make executable (chmod +x), move to a directory in your PATH.

Dependencies: Relies on external tools being in your PATH: git, and potentially terraform, pulumi, tflint, isort, black, flake8, python.

Usage

contextvibes [command] --help  # General help or help for a specific command
contextvibes [command] [flags] # Run a command

Common Flags:

  • -y, --yes: Assume 'yes' to all confirmation prompts.
  • --ai-log-file <path>: Specify a path for the detailed AI JSON log.
  • --log-level-ai <level>: Set the minimum level for the AI log file (debug, info, warn, error).

(See the Command Reference for all commands and flags.)

Examples:

# Initiate a strategic project kickoff (generates a master prompt for your AI)
contextvibes factory kickoff --strategic

# Generate an AI prompt to write your commit message
contextvibes factory commit --ai

# Generate an AI prompt to review your code
contextvibes product quality --ai

# Describe the project for an AI (prompts for task description)
contextvibes project describe -o my_context.md

Documentation

Our documentation is organized to help you find information quickly.

Guides
Reference
Development & Contributing

Important: Ignoring Generated Files

It is strongly recommended to add generated files like contextvibes.md, STRATEGIC_KICKOFF_PROTOCOL_FOR_AI.md, contextvibes_ai_trace.log, *.log, and tfplan.out to your project's .gitignore file.

Terminal Output vs. AI Log File

Context Vibes uses two distinct output mechanisms:

  1. Terminal Output (stdout/stderr): For human readability and high-level status/errors.
  2. AI Log File (JSON): Written to contextvibes_ai_trace.log by default (configurable).

Code of Conduct

Act professionally and respectfully. Be kind, considerate, and welcoming. Harassment or exclusionary behavior will not be tolerated.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Directories

Path Synopsis
cmd
Package cmd provides the entry point for the ContextVibes CLI.
 Package cmd provides the entry point for the ContextVibes CLI.
contextvibes command
Package main is the entry point for the application.
 Package main is the entry point for the application.
factory
Package factory groups commands related to the mechanical execution of the workflow.
 Package factory groups commands related to the mechanical execution of the workflow.
factory/apply
Package apply provides the command to apply changes to the project.
 Package apply provides the command to apply changes to the project.
factory/bootstrap
Package bootstrap provides the command for environment initialization.
 Package bootstrap provides the command for environment initialization.
factory/commit
Package commit provides the command to commit changes.
 Package commit provides the command to commit changes.
factory/deploy
Package deploy provides the command to deploy infrastructure.
 Package deploy provides the command to deploy infrastructure.
factory/diff
Package diff provides the command to show git diffs.
 Package diff provides the command to show git diffs.
factory/finish
Package finish provides the command to finish a feature branch.
 Package finish provides the command to finish a feature branch.
factory/init
Package initcmd provides the command to initialize the project configuration.
 Package initcmd provides the command to initialize the project configuration.
factory/kickoff
Package kickoff provides the command to start a new task or project.
 Package kickoff provides the command to start a new task or project.
factory/plan
Package plan provides the command to plan infrastructure changes.
 Package plan provides the command to plan infrastructure changes.
factory/scaffold
Package scaffold provides the command to generate infrastructure configuration.
 Package scaffold provides the command to generate infrastructure configuration.
factory/scrub
Package scrub provides the cleanup functionality for the development environment.
 Package scrub provides the cleanup functionality for the development environment.
factory/setupidentity
Package setupidentity provides the command to bootstrap the secure environment.
 Package setupidentity provides the command to bootstrap the secure environment.
factory/squash
Package squash provides the command to squash commits on a feature branch.
 Package squash provides the command to squash commits on a feature branch.
factory/status
Package status provides the command to show git status.
 Package status provides the command to show git status.
factory/sync
Package sync provides the command to synchronize the local branch with remote.
 Package sync provides the command to synchronize the local branch with remote.
factory/tidy
Package tidy provides the command to clean up merged branches.
 Package tidy provides the command to clean up merged branches.
factory/tools
Package tools provides the command to manage the development toolchain.
 Package tools provides the command to manage the development toolchain.
factory/upgradecli
Package upgradecli provides the command to update the CLI version in Nix.
 Package upgradecli provides the command to update the CLI version in Nix.
feedback
Package feedback provides the command to submit bug reports and feature requests.
 Package feedback provides the command to submit bug reports and feature requests.
library
Package library provides commands to manage the knowledge library.
 Package library provides commands to manage the knowledge library.
library/index
Package index provides the command to index project documentation.
 Package index provides the command to index project documentation.
library/systemprompt
Package systemprompt provides the command to generate system prompts.
 Package systemprompt provides the command to generate system prompts.
library/thea
Package thea provides commands to interact with the THEA framework.
 Package thea provides commands to interact with the THEA framework.
library/thea/getartifact
Package getartifact provides the command to fetch THEA artifacts.
 Package getartifact provides the command to fetch THEA artifacts.
library/vendor
Package vendor provides the command to export upstream module source code as reference material.
 Package vendor provides the command to export upstream module source code as reference material.
mcp
Package mcp provides the command to start the Model Context Protocol server.
 Package mcp provides the command to start the Model Context Protocol server.
product
Package product provides commands to manage the product.
 Package product provides commands to manage the product.
product/build
Package build provides the command to build the project.
 Package build provides the command to build the project.
product/clean
Package clean provides the command to clean project artifacts.
 Package clean provides the command to clean project artifacts.
product/codemod
Package codemod provides the command to apply code modifications.
 Package codemod provides the command to apply code modifications.
product/format
product/quality
product/run
Package run provides the command to execute example applications.
 Package run provides the command to execute example applications.
product/test
Package test provides the command to run project tests.
 Package test provides the command to run project tests.
project
Package project groups commands related to project planning and management.
 Package project groups commands related to project planning and management.
project/board
Package board provides commands to manage project boards.
 Package board provides commands to manage project boards.
project/board/add
Package add provides the command to add issues to a project board.
 Package add provides the command to add issues to a project board.
project/board/list
Package list provides the command to list project boards.
 Package list provides the command to list project boards.
project/describe
Package describe provides the command to generate a project context description.
 Package describe provides the command to generate a project context description.
project/issues
Package issues provides commands to manage project issues.
 Package issues provides commands to manage project issues.
project/issues/close
Package closecmd provides the command to close a work item (issue).
 Package closecmd provides the command to close a work item (issue).
project/issues/create
Package create provides the command to create new issues.
 Package create provides the command to create new issues.
project/issues/internal
Package internal provides internal helpers for issues commands.
 Package internal provides internal helpers for issues commands.
project/issues/list
Package list provides the command to list project issues.
 Package list provides the command to list project issues.
project/issues/tree
Package tree provides the command to display issue hierarchy.
 Package tree provides the command to display issue hierarchy.
project/issues/view
Package view provides the command to view issue details.
 Package view provides the command to view issue details.
project/labels
Package labels provides commands to manage project labels.
 Package labels provides commands to manage project labels.
project/labels/create
Package create provides the command to create labels.
 Package create provides the command to create labels.
project/onboard
Package onboard provides the command to generate a comprehensive context artifact for initializing an AI session.
 Package onboard provides the command to generate a comprehensive context artifact for initializing an AI session.
project/plan
Package plan provides commands to plan project work.
 Package plan provides commands to plan project work.
project/plan/refine
Package refine provides the command to refine issues.
 Package refine provides the command to refine issues.
project/plan/suggest-refinement
Package suggest provides the command to suggest issue refinements.
 Package suggest provides the command to suggest issue refinements.
project/summary
Package summary provides the command to display a high-level dashboard of the project's status.
 Package summary provides the command to display a high-level dashboard of the project's status.
version
Package version provides the command to display build and version information.
 Package version provides the command to display build and version information.
examples
another-example command
Package main is an example application.
 Package main is an example application.
hello-world command
Package main is an example application.
 Package main is an example application.
internal
apply
Package apply provides functionality to execute declarative change plans.
 Package apply provides functionality to execute declarative change plans.
build
Package build holds the build-time metadata injected by the linker.
 Package build holds the build-time metadata injected by the linker.
cmddocs
Package cmddocs provides functionality for parsing and executing templates used for CLI command documentation.
 Package cmddocs provides functionality for parsing and executing templates used for CLI command documentation.
codemod
Package codemod defines the data structures used to represent codification modification scripts for the contextvibes CLI.
 Package codemod defines the data structures used to represent codification modification scripts for the contextvibes CLI.
config
Package config manages the configuration for the contextvibes CLI application.
 Package config manages the configuration for the contextvibes CLI application.
config/assets
exec
Package exec provides a client and interface for executing external commands.
 Package exec provides a client and interface for executing external commands.
git
Package git provides a high-level client for interacting with Git repositories programmatically from Go applications.
 Package git provides a high-level client for interacting with Git repositories programmatically from Go applications.
github
Package github provides a client for interacting with the GitHub API.
 Package github provides a client for interacting with the GitHub API.
globals
Package globals provides global variables for the application.
 Package globals provides global variables for the application.
mcp
pipeline
Package pipeline provides an engine for running analytical workflows (quality checks).
 Package pipeline provides an engine for running analytical workflows (quality checks).
project
Package project provides functionality to detect the type of a project based on its file structure.
 Package project provides functionality to detect the type of a project based on its file structure.
scaffold
Package scaffold provides the provider for loading embedded scaffold templates.
 Package scaffold provides the provider for loading embedded scaffold templates.
thea
Package thea provides a client for interacting with the THEA framework.
 Package thea provides a client for interacting with the THEA framework.
tools
Package tools provides general utility functions used across the application.
 Package tools provides general utility functions used across the application.
ui
Package ui provides the presentation layer for the CLI, handling output formatting and user interaction.
 Package ui provides the presentation layer for the CLI, handling output formatting and user interaction.
workflow
Package workflow provides a structured engine for executing sequential, multi-step CLI operations.
 Package workflow provides a structured engine for executing sequential, multi-step CLI operations.
workitem
Package workitem provides a provider-agnostic abstraction for interacting with project management items like issues, tasks, and user stories.
 Package workitem provides a provider-agnostic abstraction for interacting with project management items like issues, tasks, and user stories.
workitem/github
Package github provides the GitHub implementation of the workitem provider.
 Package github provides the GitHub implementation of the workitem provider.
workitem/resolver
Package resolver provides functionality to build hierarchical trees of work items.
 Package resolver provides functionality to build hierarchical trees of work items.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.