qctl/README.md

qctl

Command-line interface for the QRun ecosystem. Scaffold QQQ applications, manage qBits, and deploy to qRun.

Installation

Homebrew (macOS/Linux)

brew tap QRun-IO/qctl
brew install qctl

Scoop (Windows)

scoop bucket add qrun https://github.com/QRun-IO/qctl
scoop install qctl

AUR (Arch Linux)

yay -S qctl-bin

Docker

docker run --rm ghcr.io/qrun-io/qctl:latest --help

# Mount current directory for project scaffolding
docker run --rm -v $(pwd):/work -w /work ghcr.io/qrun-io/qctl:latest qqq init new-qqq-application my-app

Pre-built Binaries

Download from Releases:

Platform	Binary
Linux x64	qctl-linux-amd64
Linux ARM64	qctl-linux-arm64
macOS Intel	qctl-macos-amd64
macOS Apple Silicon	qctl-macos-arm64
Windows	qctl-windows-amd64.exe

# Example: macOS Apple Silicon
curl -L https://github.com/QRun-IO/qctl/releases/latest/download/qctl-macos-arm64 -o qctl
chmod +x qctl
sudo mv qctl /usr/local/bin/

Build from Source

Requires GraalVM 21+:

git clone https://github.com/QRun-IO/qctl.git
cd qctl
JAVA_HOME=/path/to/graalvm mvn clean package -DskipTests -Pnative
./qctl-cli/target/qctl --version

Quick Start

# List available project templates
qctl qqq list

# Scaffold a new QQQ application
qctl qqq init new-qqq-application my-app

# With custom variables
qctl qqq init new-qqq-application my-app \
  --var=projectName=MyApp \
  --var=groupId=com.example \
  --var=package=com.example.myapp

Commands

qqq - Scaffolding

Command	Description
qctl qqq list	List available templates from the hub
qctl qqq init <template> <dir>	Initialize a new project from template

Init Options:

• --var=key=value - Set template variable
• --version=1.0.0 - Use specific template version
• --dry-run - Preview without writing files
• --force - Overwrite existing directory
• --no-prompt - Skip interactive prompts
• --skip-hooks - Skip post-generation hooks

auth - Authentication

Command	Description
qctl auth login	Authenticate to qRun APIs
qctl auth logout	Clear stored credentials

qbit - Package Management

Command	Description
qctl qbit resolve	Resolve qBit dependencies

qrun - Deployment

Command	Description
qctl qrun status	Check deployment status
qctl qrun package	Package application
qctl qrun publish	Publish to registry

cache - Maintenance

Command	Description
qctl cache clean	Clear local cache

Global Options

--debug       Enable debug logging
--verbose     Enable verbose output
--offline     Run without network access
--hermetic    Resolve strictly from lockfile
--output      Output format: text|json
--help        Show help
--version     Show version

Templates

Templates are managed in QRun-IO/templates-hub. Available templates:

ID	Description
new-qqq-application	Complete QQQ application with entities, database, and dashboard

Project Structure

qctl/
├── qctl-cli/              # Native image entry point (aggregates all modules)
├── qctl-core/             # Core commands (auth, cache)
├── qctl-shared/           # Shared utilities and constants
├── qctl-qqq/              # Scaffolding commands (init, list)
├── qctl-qbit/             # Package management commands
├── qctl-qrun/             # Deployment commands
├── qctl-qstudio/          # Planning commands
├── qctl-integration-tests/ # E2E tests with fixture templates
├── docs/                  # Architecture and design documentation
├── packaging/             # Distribution manifests (Homebrew, Scoop, AUR, Docker)
└── codestyle/             # Checkstyle config and license headers

Development

# Run all tests
mvn clean verify

# Run unit tests only
mvn test

# Run E2E tests only
mvn test -pl qctl-integration-tests

# Build native image (requires GraalVM)
JAVA_HOME=/path/to/graalvm mvn clean package -DskipTests -Pnative

# Run with JVM (faster iteration)
mvn clean package -DskipTests
java -jar qctl-cli/target/qctl-cli-0.1.0-SNAPSHOT.jar --help

Testing

The project includes comprehensive E2E tests in qctl-integration-tests/:

Test Class	Coverage
InitCommandE2ETest	CLI flags and basic init behavior
InitCommandFullE2ETest	Variable substitution, computed vars, transforms
NativeBinaryE2ETest	Native binary smoke tests (requires build)

Test fixtures in src/test/resources/fixtures/templates/ provide offline, deterministic testing.

Releasing

Create a tagged release to trigger the full CI/CD pipeline:

git tag v1.0.0
git push origin v1.0.0

This automatically:

1. Runs tests on Ubuntu
2. Builds native binaries for all platforms
3. Creates a GitHub Release with binaries attached
4. Pushes Docker image to ghcr.io/qrun-io/qctl
5. Updates package manifests (Homebrew, Scoop, AUR) with correct checksums

Distribution Channels

Channel	Package	Auto-Updated
Homebrew	packaging/homebrew/qctl.rb	Yes
Scoop	packaging/scoop/qctl.json	Yes
AUR	packaging/aur/PKGBUILD	Yes
Docker	packaging/docker/Dockerfile	Yes
GitHub	Releases page	Yes

Supported Platforms

Platform	Architecture	Binary
Linux	x64	qctl-linux-amd64
Linux	ARM64	qctl-linux-arm64
macOS	Intel	qctl-macos-amd64
macOS	Apple Silicon	qctl-macos-arm64
Windows	x64	qctl-windows-amd64.exe

License

AGPL-3.0 - See LICENSE for details.