devflow-cli

wac-devflow is a global CLI for GitLab and GitHub workflows. It provides a smooth, interactive, and cross-platform experience for managing your development pipeline.

Features

• Interactive Setup Wizards: Robust Node.js-based wizards for both global and project-level configuration.
• Cross-Platform Support: Works on Linux, macOS, and Windows (PowerShell/CMD/Git Bash).
• Arrow Key Selection: Navigate options using arrow keys in setup wizards.
• Visual Feedback: Animated spinners, progress indicators, and color-coded status messages.
• Smart Auto-Detection: Automatically detects Git providers, hosts, project paths, test runners, and SonarQube configurations.
• AI-Powered Commits: Generates conventional commit messages using Claude Code, Codex, or Gemini.
• SonarQube Auto-Fix: Fetches code quality issues and fixes them with AI agents in a retry loop.
• Global Installation: Install once, use in any repository.

Install

npm install -g wac-devflow

Quick Start

# 1. Configure this machine (tokens, hosts, AI CLI)
devflow setup

# 2. Configure the current repository (branch, tests, SonarQube)
devflow project-setup

# 3. Verify everything is configured
devflow check

# 4. Push with the full pipeline
devflow push

Commands

| Command | Description | |---|---| | devflow push | Run the full pipeline: test, commit, push, create/reuse MR/PR, and optionally fix SonarQube issues. This is the default command when you run devflow with no arguments. | | devflow setup | Interactive global setup wizard. Configures Git provider tokens, hosts, SonarQube credentials, and default AI CLI. Saves to your shell profile and ~/.devflow/config.sh. | | devflow project-setup | Interactive per-project setup. Configures target branch, SonarQube project key, test runner, and pre-push test execution. Saves to .devflow/devflow-project-setting.json. | | devflow check | Verify that all required tokens, tools, and project settings are correctly configured. Shows a detailed status report. | | devflow sonar | Fetch and display current SonarQube issues for the project. | | devflow test-msg | Preview the AI-generated commit message for your current staged/unstaged changes. | | devflow set-ai | Interactively set the default AI CLI (Claude Code, Codex, or Gemini) with auto-install support. | | devflow init | Install the pre-push Git hook in the current repository to automate the push workflow. | | devflow debug-mr | Debug GitLab merge request creation (useful for troubleshooting API issues). | | devflow version | Show the installed version of devflow-cli. Also accepts --version, -v, or -V. | | devflow help | Show usage information and all available commands. Also accepts --help or -h. |

Push Options

devflow push supports the following flags:

| Flag | Description | |---|---| | -b, --branch <name> | Override the target branch for MR/PR (e.g. main, master, develop, stage). | | -f, --fix | Fix-only mode: fetch and fix SonarQube issues without waiting for the pipeline. | | -e, --existing | Use the existing /tmp/sonar-issues.json file instead of fetching fresh issues. | | -a, --agent | Standalone AI fix mode: run the AI agent to fix SonarQube issues without the Git workflow. |

How It Works

devflow push
  1. Detect git provider, host, and project path from the remote
  2. Load project settings from .devflow/devflow-project-setting.json
  3. Run tests before push (if configured)
  4. Stage all changes and generate an AI commit message
  5. Sync with the target branch (merge origin/<target>)
  6. Push the branch to the remote
  7. Create or reuse a merge request / pull request
  8. Wait for CI pipeline to complete
  9. If SonarQube is enabled and pipeline fails:
     a. Fetch SonarQube issues
     b. Run AI agent to fix issues
     c. Commit fixes and push
     d. Retry (up to MAX_RETRIES times)

Project Settings

Project-level settings are stored in the repository at:

.devflow/devflow-project-setting.json

This file is safe to commit. It is created by devflow project-setup.

Example:

{
  "mainBranch": "develop",
  "sonar": {
    "enabled": true,
    "projectKey": "myorg_myrepo_123"
  },
  "tests": {
    "runner": "jest",
    "command": "npm test",
    "runBeforePush": false
  }
}

Environment Variables

Required (set via devflow setup)

| Variable | When Required | Description | |---|---|---| | GITLAB_TOKEN | GitLab projects | Personal access token. Scopes: api, write_repository. | | GITHUB_TOKEN | GitHub projects | Personal access token. Scope: repo (or workflow for Actions). |

Optional

| Variable | Default | Description | |---|---|---| | GIT_PROVIDER | gitlab | Git provider: gitlab or github. | | GITLAB_HOST | https://gitlab.com | GitLab instance URL. | | GITHUB_HOST | https://github.com | GitHub instance URL. | | GITLAB_PROJECT_PATH | Auto-detected | Fallback if remote auto-detection is unavailable. | | GITHUB_PROJECT_PATH | Auto-detected | Fallback if remote auto-detection is unavailable. | | MAIN_BRANCH | develop (GitLab), main (GitHub) | Target branch for MRs/PRs. | | USE_SONAR | Auto | 1 to enable, 0 to disable SonarQube. | | SONAR_TOKEN | — | SonarQube API token. | | SONAR_HOST | — | SonarQube server URL. | | SONAR_PROJECT_KEY | — | SonarQube project key. | | MAX_RETRIES | 3 | Number of SonarQube fix retry iterations. | | SKIP_SONAR | — | Set to 1 to skip the pre-push SonarQube check. | | DEVFLOW_DEFAULT_AI_CLI | — | Preferred AI CLI: claude, codex, or gemini. |

Auto-Detection

devflow automatically detects the following from your repository:

• Git provider — inferred from the remote URL (github.com vs everything else).
• Git host — extracted from HTTPS or SSH remote URLs.
• Project path — extracted from the remote URL (e.g. myorg/my-repo).
• Target branch — from project settings, or defaults to develop (GitLab) / main (GitHub).
• Test runner — detected from config files (jest.config.*, vitest.config.*, etc.) or package.json scripts.
• SonarQube — inferred from project files, environment variables, or project settings.

Requirements

• Node.js 16+
• Git
• curl
• Python 3 (for SonarQube issue parsing and JSON handling)
• Git Bash on Windows (for Bash-only commands)
• Optional: Claude Code CLI, Codex CLI, or Gemini CLI (for AI commit messages and SonarQube auto-fix)

Platform Notes

macOS / Linux

• Tokens are saved to your shell profile (~/.zshrc, ~/.bashrc, or ~/.bash_profile) and to ~/.devflow/config.sh.
• The CLI automatically loads ~/.devflow/config.sh so tokens work even in non-login shells (e.g. IDE terminals).

Windows

• Tokens are saved as User-level environment variables via PowerShell.
• The CLI reads User-level and Machine-level environment variables at startup.
• PowerShell scripts (.ps1) are used when available; otherwise falls back to batch (.bat) or Git Bash.

Troubleshooting

Tokens show as "not set" after running setup

Open a new terminal, or run:

source ~/.zshrc        # macOS/Linux (zsh)
source ~/.bashrc       # Linux (bash)
source ~/.bash_profile # macOS (bash)

On Windows, close and reopen your terminal after running devflow setup.

Wrong project detected

Check your git remote:

git remote get-url origin

If incorrect, update it with git remote set-url origin <url>.

Tests fail before push

Either fix the tests or disable automatic test execution:

devflow project-setup

Set "Run tests before push" to No, or edit .devflow/devflow-project-setting.json and set tests.runBeforePush to false.

SonarQube issues not found

Verify your SonarQube configuration:

devflow check

Make sure SONAR_TOKEN, SONAR_HOST, and SONAR_PROJECT_KEY are all set correctly.

License

MIT