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

docs: restructure cmd docs to mirror CLI hierarchy

Browse source 
- Convert flat .md files to index.md in subdirectories
- Add subcommand directories (go/test, go/cov, build/sdk, etc.)
- Update dev/index.md to include multi-repo commands
- Structure now mirrors: core <cmd> [subcmd] → docs/cmd/<cmd>/<subcmd>/

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider 2026-01-29 14:46:31 +00:00
parent c9ebb7c781
commit ace6306233
23 changed files with 254 additions and 318 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

171
docs/cmd/build.md
View file

@ -1,171 +0,0 @@
# core build
Build Go, Wails, Docker, and LinuxKit projects with automatic project detection.
## Usage
```bash
core build [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--type` | Project type: `go`, `wails`, `docker`, `linuxkit` (auto-detected) |
| `--targets` | Build targets: `linux/amd64,darwin/arm64,windows/amd64` |
| `--output` | Output directory (default: `dist`) |
| `--ci` | CI mode - non-interactive, fail fast |
| `--image` | Docker image name (for docker builds) |
| `--no-sign` | Skip code signing |
| `--notarize` | Enable macOS notarization (requires Apple credentials) |
## Examples
### Go Project
```bash
# Auto-detect and build
core build
# Build for specific platforms
core build --targets linux/amd64,linux/arm64,darwin/arm64
# CI mode
core build --ci
```
### Wails Project
```bash
# Build Wails desktop app
core build --type wails
# Build for all desktop platforms
core build --type wails --targets darwin/amd64,darwin/arm64,windows/amd64,linux/amd64
```
### Docker Image
```bash
# Build Docker image
core build --type docker
# With custom image name
core build --type docker --image ghcr.io/myorg/myapp
```
### LinuxKit Image
```bash
# Build LinuxKit ISO
core build --type linuxkit
```
## Project Detection
Core automatically detects project type based on files:
| Files | Type |
|-------|------|
| `wails.json` | Wails |
| `go.mod` | Go |
| `Dockerfile` | Docker |
| `composer.json` | PHP |
| `package.json` | Node |
## Output
Build artifacts are placed in `dist/` by default:
```
dist/
├── myapp-linux-amd64.tar.gz
├── myapp-linux-arm64.tar.gz
├── myapp-darwin-amd64.tar.gz
├── myapp-darwin-arm64.tar.gz
├── myapp-windows-amd64.zip
└── CHECKSUMS.txt
```
## Configuration
Optional `.core/build.yaml`:
```yaml
version: 1
project:
name: myapp
binary: myapp
build:
main: ./cmd/myapp
ldflags:
- -s -w
- -X main.version={{.Version}}
targets:
- os: linux
arch: amd64
- os: linux
arch: arm64
- os: darwin
arch: arm64
sign:
enabled: true
gpg:
key: $GPG_KEY_ID
macos:
identity: "Developer ID Application: Your Name (TEAM_ID)"
notarize: false
apple_id: $APPLE_ID
team_id: $APPLE_TEAM_ID
app_password: $APPLE_APP_PASSWORD
```
## Code Signing
Core supports GPG signing for checksums and native code signing for macOS.
### GPG Signing
Signs `CHECKSUMS.txt` with a detached ASCII signature (`.asc`):
```bash
# Build with GPG signing (default if key configured)
core build
# Skip signing
core build --no-sign
```
Users can verify:
```bash
gpg --verify CHECKSUMS.txt.asc CHECKSUMS.txt
sha256sum -c CHECKSUMS.txt
```
### macOS Code Signing
Signs Darwin binaries with your Developer ID and optionally notarizes with Apple:
```bash
# Build with codesign (automatic if identity configured)
core build
# Build with notarization (takes 1-5 minutes)
core build --notarize
```
### Environment Variables
| Variable | Purpose |
|----------|---------|
| `GPG_KEY_ID` | GPG key ID or fingerprint |
| `CODESIGN_IDENTITY` | macOS Developer ID (fallback) |
| `APPLE_ID` | Apple account email |
| `APPLE_TEAM_ID` | Apple Developer Team ID |
| `APPLE_APP_PASSWORD` | App-specific password for notarization |

0
docs/cmd/release.md → docs/cmd/ci/index.md
View file

46
docs/cmd/dev.md → docs/cmd/dev/index.md
View file

@ -1,24 +1,40 @@
# core dev
Portable development environment with 100+ embedded tools.
Multi-repo development workflow and portable dev environment.
## Overview
Core DevOps provides a sandboxed, immutable development environment based on LinuxKit. It includes AI tools (Claude, Gemini), runtimes (Go, Node, PHP, Python, Rust), and infrastructure tools (Docker, Kubernetes, Terraform).
## Commands
## Multi-Repo Commands
| Command | Description |
|---------|-------------|
| `install` | Download the core-devops image for your platform |
| `boot` | Start the development environment |
| `stop` | Stop the running environment |
| `status` | Show environment status |
| `shell` | Open a shell in the environment |
| `serve` | Mount project and start dev server |
| `test` | Run tests inside the environment |
| `claude` | Start sandboxed Claude session |
| `update` | Update to latest image |
| [work](work/) | Full workflow: status + commit + push |
| [health](health/) | Quick health check across repos |
| [commit](commit/) | Claude-assisted commits |
| [push](push/) | Push repos with unpushed commits |
| [pull](pull/) | Pull repos that are behind |
| [issues](issues/) | List open issues |
| [reviews](reviews/) | List PRs needing review |
| [ci](ci/) | Check CI status |
| [impact](impact/) | Show dependency impact |
## Dev Environment Commands
| Command | Description |
|---------|-------------|
| [install](install/) | Download the core-devops image |
| [boot](boot/) | Start the environment |
| [stop](stop/) | Stop the environment |
| [status](status/) | Show status |
| [shell](shell/) | Open shell |
| [serve](serve/) | Start dev server |
| [test](test/) | Run tests |
| [claude](claude/) | Sandboxed Claude |
| [update](update/) | Update image |
---
## Dev Environment Overview
Core DevOps provides a sandboxed, immutable development environment based on LinuxKit with 100+ embedded tools.
## Quick Start

0
docs/cmd/work.md → docs/cmd/dev/work/index.md
View file

0
docs/cmd/docs.md → docs/cmd/docs/index.md
View file

0
docs/cmd/doctor.md → docs/cmd/doctor/index.md
View file

28
docs/cmd/go/cov/index.md Normal file
View file

@ -0,0 +1,28 @@
# core go cov
Generate coverage report with thresholds.
## Usage
```bash
core go cov [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--pkg` | Package to test (default: `./...`) |
| `--html` | Generate HTML report |
| `--open` | Open in browser |
| `--threshold` | Fail if coverage below % |
## Examples
```bash
core go cov # Summary
core go cov --html # HTML report
core go cov --open # Open in browser
core go cov --threshold 80 # Fail if < 80%
core go cov --pkg ./pkg/release # Specific package
```

24
docs/cmd/go/fmt/index.md Normal file
View file

@ -0,0 +1,24 @@
# core go fmt
Format Go code using goimports or gofmt.
## Usage
```bash
core go fmt [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--fix` | Apply fixes (default: check only) |
| `--diff` | Show diff |
## Examples
```bash
core go fmt # Check
core go fmt --fix # Apply fixes
core go fmt --diff # Show diff
```

14
docs/cmd/go/index.md Normal file
View file

@ -0,0 +1,14 @@
# core go
Go development tools.
## Subcommands
| Command | Description |
|---------|-------------|
| [test](test/) | Run tests |
| [cov](cov/) | Coverage report |
| [fmt](fmt/) | Format code |
| [lint](lint/) | Lint code |
| [install](install/) | Install binary |
| [mod](mod/) | Module management |

24
docs/cmd/go/install/index.md Normal file
View file

@ -0,0 +1,24 @@
# core go install
Install Go binary with auto-detection.
## Usage
```bash
core go install [path] [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--no-cgo` | Disable CGO |
| `-v` | Verbose |
## Examples
```bash
core go install # Auto-detect cmd/
core go install ./cmd/core # Specific path
core go install --no-cgo # Pure Go
```

22
docs/cmd/go/lint/index.md Normal file
View file

@ -0,0 +1,22 @@
# core go lint
Run golangci-lint.
## Usage
```bash
core go lint [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--fix` | Auto-fix issues |
## Examples
```bash
core go lint # Check
core go lint --fix # Auto-fix
```

21
docs/cmd/go/mod/index.md Normal file
View file

@ -0,0 +1,21 @@
# core go mod
Module management.
## Subcommands
| Command | Description |
|---------|-------------|
| `tidy` | Tidy go.mod |
| `download` | Download dependencies |
| `verify` | Verify dependencies |
| `graph` | Show dependency graph |
## Examples
```bash
core go mod tidy
core go mod download
core go mod verify
core go mod graph
```

31
docs/cmd/go/test/index.md Normal file
View file

@ -0,0 +1,31 @@
# core go test
Run Go tests with coverage and filtered output.
## Usage
```bash
core go test [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--pkg` | Package to test (default: `./...`) |
| `--run` | Run specific tests |
| `--short` | Skip long-running tests |
| `--race` | Enable race detection |
| `--coverage` | Show coverage summary |
| `--json` | JSON output for CI |
| `-v` | Verbose output |
## Examples
```bash
core go test # All tests
core go test --pkg ./pkg/core # Specific package
core go test --run TestHash # Specific test
core go test --coverage # With coverage
core go test --race # Race detection
```

27
docs/cmd/index.md Normal file
View file

@ -0,0 +1,27 @@
# Core CLI
Unified interface for Go/PHP development, multi-repo management, and deployment.
## Commands
| Command | Description |
|---------|-------------|
| [go](go/) | Go development tools |
| [php](php/) | Laravel/PHP development tools |
| [build](build/) | Build projects |
| [ci](ci/) | Publish releases |
| [sdk](sdk/) | SDK validation |
| [dev](dev/) | Multi-repo workflow + dev environment |
| [pkg](pkg/) | Package management |
| [vm](vm/) | LinuxKit VM management |
| [docs](docs/) | Documentation management |
| [setup](setup/) | Clone repos |
| [doctor](doctor/) | Check environment |
## Installation
```bash
core go install
```
Verify: `core doctor`

0
docs/cmd/php.md → docs/cmd/php/index.md
View file

13
docs/cmd/pkg/index.md Normal file
View file

@ -0,0 +1,13 @@
# core pkg
Package management for core-* repos.
## Subcommands
| Command | Description |
|---------|-------------|
| [search](search/) | Search packages |
| [install](install/) | Install package |
| [list](list/) | List installed |
| [update](update/) | Update packages |
| [outdated](outdated/) | Check outdated |

0
docs/cmd/search.md → docs/cmd/pkg/search/index.md
View file

132
docs/cmd/run.md
View file

@ -1,132 +0,0 @@
# core run
Run LinuxKit images with qemu or hyperkit.
## Usage
```bash
core run <image> [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `-d, --detach` | Run in background |
| `--cpus` | Number of CPUs (default: 1) |
| `--mem` | Memory in MB (default: 1024) |
| `--disk` | Disk size (default: none) |
| `--template` | Use built-in template |
## Examples
### Run ISO Image
```bash
# Run LinuxKit ISO
core run server.iso
# With more resources
core run server.iso --cpus 2 --mem 2048
# Detached mode
core run server.iso -d
```
### Run from Template
```bash
# List available templates
core templates
# Run template
core run --template core-dev
```
### Formats
Supported image formats:
- `.iso` - Bootable ISO
- `.qcow2` - QEMU disk image
- `.raw` - Raw disk image
- `.vmdk` - VMware disk
## Container Management
```bash
# List running containers
core ps
# View logs
core logs <id>
# Follow logs
core logs -f <id>
# Execute command
core exec <id> <command>
# Stop container
core stop <id>
```
## Templates
Built-in templates in `.core/linuxkit/`:
| Template | Description |
|----------|-------------|
| `core-dev` | Development environment |
| `server-php` | FrankenPHP server |
### Custom Templates
Create `.core/linuxkit/mytemplate.yml`:
```yaml
kernel:
image: linuxkit/kernel:6.6
cmdline: "console=tty0"
init:
- linuxkit/init:latest
- linuxkit/runc:latest
- linuxkit/containerd:latest
services:
- name: myservice
image: myorg/myservice:latest
files:
- path: /etc/myconfig
contents: |
key: value
```
Then run:
```bash
core run --template mytemplate
```
## Networking
LinuxKit VMs get their own network namespace. Port forwarding:
```bash
# Forward port 8080
core run server.iso -p 8080:80
# Multiple ports
core run server.iso -p 8080:80 -p 8443:443
```
## Disk Persistence
```bash
# Create persistent disk
core run server.iso --disk 10G
# Attach existing disk
core run server.iso --disk /path/to/disk.qcow2
```

0
docs/cmd/sdk.md → docs/cmd/sdk/index.md
View file

0
docs/cmd/setup.md → docs/cmd/setup/index.md
View file

5
docs/cmd/test/index.md Normal file
View file

@ -0,0 +1,5 @@
# core test
Run tests (legacy command).
**Prefer:** `core go test` or `core php test`

14
docs/cmd/vm/index.md Normal file
View file

@ -0,0 +1,14 @@
# core vm
LinuxKit VM management.
## Subcommands
| Command | Description |
|---------|-------------|
| [run](run/) | Run VM |
| [ps](ps/) | List VMs |
| [stop](stop/) | Stop VM |
| [logs](logs/) | View logs |
| [exec](exec/) | Execute command |
| [templates](templates/) | Manage templates |

0
docs/cmd/templates.md → docs/cmd/vm/templates/index.md
View file