Command-line interface for the QRun ecosystem. Scaffold QQQ applications, manage qBits, and deploy to qRun.
brew tap QRun-IO/qctl
brew install qctlscoop bucket add qrun https://github.com/QRun-IO/qctl
scoop install qctlyay -S qctl-bindocker 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-appDownload 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/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# 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| 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
| Command | Description |
|---|---|
qctl auth login |
Authenticate to qRun APIs |
qctl auth logout |
Clear stored credentials |
| Command | Description |
|---|---|
qctl qbit resolve |
Resolve qBit dependencies |
| Command | Description |
|---|---|
qctl qrun status |
Check deployment status |
qctl qrun package |
Package application |
qctl qrun publish |
Publish to registry |
| Command | Description |
|---|---|
qctl cache clean |
Clear local cache |
--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 are managed in QRun-IO/templates-hub. Available templates:
| ID | Description |
|---|---|
new-qqq-application |
Complete QQQ application with entities, database, and dashboard |
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
├── docs/ # Architecture and design documentation
├── packaging/ # Distribution manifests (Homebrew, Scoop, AUR, Docker)
└── codestyle/ # Checkstyle config and license headers
# Run tests
mvn clean verify
# 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 --helpCreate a tagged release to trigger the full CI/CD pipeline:
git tag v1.0.0
git push origin v1.0.0This automatically:
- Runs tests on Ubuntu
- Builds native binaries for all platforms
- Creates a GitHub Release with binaries attached
- Pushes Docker image to
ghcr.io/qrun-io/qctl - Updates package manifests (Homebrew, Scoop, AUR) with correct checksums
| 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 |
| 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 |
AGPL-3.0 - See LICENSE for details.