core/cli
8
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions 1

docs: add example.md files and ci subcommands

Browse source 
- Add example.md alongside index.md for config/usage samples
- Add ci subcommands: init, changelog, version
- Fix ci/index.md to reference correct commands (was release)
- Update references from config.md to example.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider 2026-01-29 14:54:44 +00:00
parent ace6306233
commit eed8a030f1
9 changed files with 528 additions and 169 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

28
docs/cmd/ci/changelog/index.md Normal file
View file

@ -0,0 +1,28 @@
# core ci changelog
Generate changelog from conventional commits.
## Usage
```bash
core ci changelog
```
## Output
Generates markdown changelog from git commits since last tag:
```markdown
## v1.2.0
### Features
- Add user authentication (#123)
- Support dark mode (#124)
### Bug Fixes
- Fix memory leak in worker (#125)
```
## Configuration
See [config.md](../config.md) for changelog configuration options.

90
docs/cmd/ci/example.md Normal file
View file

@ -0,0 +1,90 @@
# CI Examples
## Quick Start
```bash
# Build first
core build
# Preview release
core ci
# Publish
core ci --were-go-for-launch
```
## Configuration
`.core/release.yaml`:
```yaml
version: 1
project:
name: myapp
repository: host-uk/myapp
publishers:
- type: github
```
## Publisher Examples
### GitHub + Docker
```yaml
publishers:
- type: github
- type: docker
registry: ghcr.io
image: host-uk/myapp
platforms:
- linux/amd64
- linux/arm64
tags:
- latest
- "{{.Version}}"
```
### Full Stack (GitHub + npm + Homebrew)
```yaml
publishers:
- type: github
- type: npm
package: "@host-uk/myapp"
access: public
- type: homebrew
tap: host-uk/homebrew-tap
```
### LinuxKit Image
```yaml
publishers:
- type: linuxkit
config: .core/linuxkit/server.yml
formats:
- iso
- qcow2
platforms:
- linux/amd64
- linux/arm64
```
## Changelog Configuration
```yaml
changelog:
include:
- feat
- fix
- perf
exclude:
- chore
- docs
- test
```

216
docs/cmd/ci/index.md
View file

@ -1,201 +1,79 @@
# core release # core ci
Build and publish releases to GitHub, npm, Homebrew, Scoop, AUR, Chocolatey, Docker, and LinuxKit. Publish releases to GitHub, Docker, npm, Homebrew, and more.
**Safety:** Dry-run by default. Use `--were-go-for-launch` to actually publish.
## Subcommands
| Command | Description |
|---------|-------------|
| [init](init/) | Initialize release config |
| [changelog](changelog/) | Generate changelog |
| [version](version/) | Show determined version |
## Usage ## Usage
```bash ```bash
core release [flags] core ci [flags]
``` ```
## Flags ## Flags
| Flag | Description | | Flag | Description |
|------|-------------| |------|-------------|
| `--dry-run` | Preview what would be published | | `--were-go-for-launch` | Actually publish (default is dry-run) |
| `--version` | Override version (default: git tag) | | `--version` | Override version |
| `--target` | Release target: `sdk` for SDK-only release | | `--draft` | Create as draft release |
| `--draft` | Create release as draft | | `--prerelease` | Mark as prerelease |
| `--prerelease` | Mark release as prerelease |
## Quick Start ## Examples
```bash ```bash
# Initialize release config # Preview what would be published (safe)
core release init core ci
# Preview release # Actually publish
core release --dry-run core ci --were-go-for-launch
# Release # Publish as draft
core release core ci --were-go-for-launch --draft
# SDK-only release # Publish as prerelease
core release --target sdk core ci --were-go-for-launch --prerelease
``` ```
## SDK Release ## Workflow
Generate SDKs without building binaries: Build and publish are **separated** to prevent accidents:
```bash ```bash
# Generate SDKs with version from git tag # Step 1: Build artifacts
core release --target sdk core build
core build sdk
# Explicit version # Step 2: Preview (dry-run by default)
core release --target sdk --version v1.2.3 core ci
# Preview # Step 3: Publish (explicit flag required)
core release --target sdk --dry-run core ci --were-go-for-launch
``` ```
This will:
1. Determine version from git tags (or `--version` flag)
2. Run breaking change detection if configured
3. Generate SDKs for all configured languages
4. Output to `sdk/` directory
See [SDK commands](sdk.md) for more details.
## Publishers ## Publishers
### GitHub Releases See [example.md](example.md) for publisher configuration.
Uploads artifacts and changelog to GitHub Releases. | Type | Target |
|------|--------|
```yaml | `github` | GitHub Releases |
publishers: | `docker` | Container registries |
- type: github | `linuxkit` | LinuxKit images |
prerelease: false | `npm` | npm registry |
draft: false | `homebrew` | Homebrew tap |
``` | `scoop` | Scoop bucket |
| `aur` | Arch User Repository |
### npm | `chocolatey` | Chocolatey |
Publishes binary wrapper that downloads correct platform binary.
```yaml
publishers:
- type: npm
package: "@myorg/myapp"
access: public
```
Requires `NPM_TOKEN` environment variable.
### Homebrew
Generates formula and commits to tap repository.
```yaml
publishers:
- type: homebrew
tap: myorg/homebrew-tap
formula: myapp # optional, defaults to project name
```
For official Homebrew PR:
```yaml
publishers:
- type: homebrew
tap: myorg/homebrew-tap
official:
enabled: true
output: dist/homebrew
```
### Scoop
Generates manifest and commits to bucket repository.
```yaml
publishers:
- type: scoop
bucket: myorg/scoop-bucket
```
### AUR
Generates PKGBUILD and pushes to AUR.
```yaml
publishers:
- type: aur
maintainer: "Your Name <email@example.com>"
```
### Chocolatey
Generates NuSpec and optionally pushes to Chocolatey.
```yaml
publishers:
- type: chocolatey
push: false # generate only
```
Set `push: true` and `CHOCOLATEY_API_KEY` to publish.
### Docker
Builds and pushes multi-arch Docker images.
```yaml
publishers:
- type: docker
registry: ghcr.io
image: myorg/myapp
platforms:
- linux/amd64
- linux/arm64
tags:
- latest
- "{{.Version}}"
```
### LinuxKit
Builds immutable LinuxKit images.
```yaml
publishers:
- type: linuxkit
config: .core/linuxkit/server.yml
formats:
- iso
- qcow2
- docker # Immutable container
platforms:
- linux/amd64
- linux/arm64
```
## Full Example
See [examples/full-release.yaml](examples/full-release.yaml) for a complete configuration.
## Changelog ## Changelog
Changelog is auto-generated from conventional commits: Auto-generated from conventional commits. See [example.md](example.md) for configuration.
```
feat: Add new feature → Features
fix: Fix bug → Bug Fixes
perf: Improve performance → Performance
refactor: Refactor code → Refactoring
```
Configure in `.core/release.yaml`:
```yaml
changelog:
include:
- feat
- fix
- perf
exclude:
- chore
- docs
- test
```

25
docs/cmd/ci/init/index.md Normal file
View file

@ -0,0 +1,25 @@
# core ci init
Initialize release configuration.
## Usage
```bash
core ci init
```
Creates `.core/release.yaml` with default configuration.
## Example Output
```yaml
version: 1
project:
name: myapp
publishers:
- type: github
```
See [config.md](../config.md) for full configuration options.

21
docs/cmd/ci/version/index.md Normal file
View file

@ -0,0 +1,21 @@
# core ci version
Show the determined release version.
## Usage
```bash
core ci version
```
## Output
```
v1.2.0
```
Version is determined from:
1. `--version` flag (if provided)
2. Git tag on HEAD
3. Latest git tag + increment
4. `v0.0.1` (if no tags exist)

87
docs/cmd/dev/example.md Normal file
View file

@ -0,0 +1,87 @@
# Dev Examples
## Multi-Repo Workflow
```bash
# Quick status
core dev health
# Full workflow
core dev work
# Status only
core dev work --status
# Commit dirty repos
core dev commit
# Push unpushed
core dev push
# Pull behind
core dev pull
```
## GitHub Integration
```bash
# Open issues
core dev issues
# Include closed
core dev issues --all
# PRs needing review
core dev reviews
# CI status
core dev ci
```
## Dependency Analysis
```bash
# What depends on core-php?
core dev impact core-php
```
## Dev Environment
```bash
# First time setup
core dev install
core dev boot
# Open shell
core dev shell
# Mount and serve
core dev serve
# Run tests
core dev test
# Sandboxed Claude
core dev claude
```
## Configuration
`repos.yaml`:
```yaml
org: host-uk
repos:
core-php:
type: package
description: Foundation framework
core-tenant:
type: package
depends: [core-php]
```
`~/.core/config.yaml`:
```yaml
version: 1
images:
source: auto
```

89
docs/cmd/go/example.md Normal file
View file

@ -0,0 +1,89 @@
# Go Examples
## Testing
```bash
# Run all tests
core go test
# Specific package
core go test --pkg ./pkg/core
# Specific test
core go test --run TestHash
# With coverage
core go test --coverage
# Race detection
core go test --race
```
## Coverage
```bash
# Summary
core go cov
# HTML report
core go cov --html
# Open in browser
core go cov --open
# Fail if below threshold
core go cov --threshold 80
```
## Formatting
```bash
# Check
core go fmt
# Fix
core go fmt --fix
# Show diff
core go fmt --diff
```
## Linting
```bash
# Check
core go lint
# Auto-fix
core go lint --fix
```
## Installing
```bash
# Auto-detect cmd/
core go install
# Specific path
core go install ./cmd/myapp
# Pure Go (no CGO)
core go install --no-cgo
```
## Module Management
```bash
core go mod tidy
core go mod download
core go mod verify
core go mod graph
```
## Workspace
```bash
core go work sync
core go work init
core go work use ./pkg/mymodule
```

89
docs/cmd/php/example.md Normal file
View file

@ -0,0 +1,89 @@
# PHP Examples
## Development
```bash
# Start all services
core php dev
# With HTTPS
core php dev --https
# Skip services
core php dev --no-vite --no-horizon
```
## Testing
```bash
# Run all
core php test
# Parallel
core php test --parallel
# With coverage
core php test --coverage
# Filter
core php test --filter UserTest
```
## Code Quality
```bash
# Format
core php fmt --fix
# Static analysis
core php analyse --level 9
```
## Deployment
```bash
# Production
core php deploy
# Staging
core php deploy --staging
# Wait for completion
core php deploy --wait
# Check status
core php deploy:status
# Rollback
core php deploy:rollback
```
## Configuration
`.env`:
```env
COOLIFY_URL=https://coolify.example.com
COOLIFY_TOKEN=your-api-token
COOLIFY_APP_ID=production-app-id
COOLIFY_STAGING_APP_ID=staging-app-id
```
## Package Linking
```bash
# Link local packages
core php packages link ../my-package
# Update linked
core php packages update
# Unlink
core php packages unlink my-package
```
## SSL Setup
```bash
core php ssl
core php ssl --domain myapp.test
```

52
docs/cmd/vm/example.md Normal file
View file

@ -0,0 +1,52 @@
# VM Examples
## Running VMs
```bash
# Run image
core vm run server.iso
# Detached with resources
core vm run -d --memory 4096 --cpus 4 server.iso
# From template
core vm run --template core-dev --var SSH_KEY="ssh-rsa AAAA..."
```
## Management
```bash
# List running
core vm ps
# Include stopped
core vm ps -a
# Stop
core vm stop abc123
# View logs
core vm logs abc123
# Follow logs
core vm logs -f abc123
# Execute command
core vm exec abc123 ls -la
# Shell
core vm exec abc123 /bin/sh
```
## Templates
```bash
# List
core vm templates
# Show content
core vm templates show core-dev
# Show variables
core vm templates vars core-dev
```