From 76872efbd7a97386c0b1bdaff7bc43e654ab850c Mon Sep 17 00:00:00 2001 From: Snider Date: Thu, 29 Jan 2026 16:27:39 +0000 Subject: [PATCH] docs: complete CLI documentation sync - pkg search: add --pattern, --type, --refresh, --limit, --org flags - sdk: remove generate (use core build sdk), keep only diff/validate - vm run: add --ssh-port, --name, fix defaults - TODO.md: all gaps resolved Co-Authored-By: Claude Opus 4.5 --- docs/cmd/TODO.md | 20 +------ docs/cmd/pkg/search/index.md | 97 ++++++++++-------------------- docs/cmd/sdk/index.md | 113 ++++++----------------------------- docs/cmd/vm/index.md | 8 ++- 4 files changed, 54 insertions(+), 184 deletions(-) diff --git a/docs/cmd/TODO.md b/docs/cmd/TODO.md index c24d6f3..41146ae 100644 --- a/docs/cmd/TODO.md +++ b/docs/cmd/TODO.md @@ -1,21 +1,5 @@ # Documentation TODO -Commands and flags found in CLI but missing from documentation. +All CLI commands are documented. No gaps found. -## Missing Flags - -### core pkg search - -- `--refresh` - Bypass cache and fetch fresh data -- `--type` - Filter by type in name (mod, services, plug, website) - -### core vm run - -- `--ssh-port` - SSH port for exec commands (default: 2222) - -## Discrepancies - -### core sdk - -- Docs describe `core sdk generate` command but CLI only has `core sdk diff` and `core sdk validate` -- SDK generation is actually at `core build sdk`, not `core sdk generate` +Last verified: 2026-01-29 diff --git a/docs/cmd/pkg/search/index.md b/docs/cmd/pkg/search/index.md index 0b923a5..57fea91 100644 --- a/docs/cmd/pkg/search/index.md +++ b/docs/cmd/pkg/search/index.md @@ -1,40 +1,48 @@ -# core pkg search & core pkg install - -Search GitHub for repositories and install them locally. - -## core pkg search +# core pkg search Search GitHub for repositories matching a pattern. +Uses `gh` CLI for authenticated search. Results are cached for 1 hour. + +## Usage + ```bash -core pkg search [flags] +core pkg search [flags] ``` -### Flags +## Flags | Flag | Description | |------|-------------| -| `--org` | Search within a specific organization | -| `--limit` | Maximum results (default: 10) | -| `--language` | Filter by programming language | +| `--pattern` | Repo name pattern (* for wildcard) | +| `--org` | GitHub organization (default: host-uk) | +| `--type` | Filter by type in name (mod, services, plug, website) | +| `--limit` | Max results (default: 50) | +| `--refresh` | Bypass cache and fetch fresh data | -### Examples +## Examples ```bash -# Search by pattern -core pkg search "cli tool" +# List all host-uk repos +core pkg search -# Search within organization -core pkg search --org host-uk +# Search for core-* repos +core pkg search --pattern "core-*" -# Search with language filter -core pkg search --org host-uk --language go +# Search different org +core pkg search --org mycompany -# Search all core-* repos -core pkg search "core-" --org host-uk +# Filter by type +core pkg search --type services + +# Bypass cache +core pkg search --refresh + +# Combine filters +core pkg search --pattern "core-*" --type mod --limit 20 ``` -### Output +## Output ``` Found 5 repositories: @@ -52,39 +60,7 @@ Found 5 repositories: ★ 8 Dockerfile Updated 3 days ago ``` -## core pkg install - -Clone a repository from GitHub. - -```bash -core pkg install [flags] -``` - -### Flags - -| Flag | Description | -|------|-------------| -| `--path` | Destination directory (default: current dir) | -| `--branch` | Clone specific branch | -| `--depth` | Shallow clone depth | - -### Examples - -```bash -# Install by full name -core pkg install host-uk/core - -# Install to specific path -core pkg install host-uk/core --path ~/Code/host-uk - -# Install specific branch -core pkg install host-uk/core --branch dev - -# Shallow clone -core pkg install host-uk/core --depth 1 -``` - -### Authentication +## Authentication Uses GitHub CLI (`gh`) authentication. Ensure you're logged in: @@ -93,20 +69,7 @@ gh auth status gh auth login # if not authenticated ``` -## Workflow Example - -```bash -# Find repositories -core pkg search --org host-uk - -# Install one -core pkg install host-uk/core-php --path ~/Code/host-uk - -# Check setup -core doctor -``` - ## See Also +- [pkg install](../) - Clone a package from GitHub - [setup command](../../setup/) - Clone all repos from registry -- [doctor command](../../doctor/) - Check environment diff --git a/docs/cmd/sdk/index.md b/docs/cmd/sdk/index.md index c979233..bd6828c 100644 --- a/docs/cmd/sdk/index.md +++ b/docs/cmd/sdk/index.md @@ -1,6 +1,8 @@ # core sdk -Generate typed API clients from OpenAPI specifications. +SDK validation and API compatibility tools. + +To generate SDKs, use: `core build sdk` ## Usage @@ -12,46 +14,8 @@ core sdk [flags] | Command | Description | |---------|-------------| -| `generate` | Generate SDKs from OpenAPI spec | -| `validate` | Validate OpenAPI spec | | `diff` | Check for breaking API changes | - -## sdk generate - -Generate typed API clients for multiple languages. - -```bash -core sdk generate [flags] -``` - -### Flags - -| Flag | Description | -|------|-------------| -| `--spec` | Path to OpenAPI spec file (auto-detected) | -| `--lang` | Generate only this language | - -### Examples - -```bash -# Generate all configured SDKs -core sdk generate - -# Generate only TypeScript SDK -core sdk generate --lang typescript - -# Use specific spec file -core sdk generate --spec api/openapi.yaml -``` - -### Supported Languages - -| Language | Generator | -|----------|-----------| -| TypeScript | openapi-generator (typescript-fetch) | -| Python | openapi-generator (python) | -| Go | openapi-generator (go) | -| PHP | openapi-generator (php) | +| `validate` | Validate OpenAPI spec | ## sdk validate @@ -109,48 +73,22 @@ core sdk diff --base old-api.yaml --spec new-api.yaml - Removed required fields - Changed response types -## Release Integration +## SDK Generation -SDKs can be generated before publishing a release: +SDK generation is handled by `core build sdk`, not this command. ```bash -# Generate all configured SDKs -core sdk generate +# Generate SDKs +core build sdk -# Then publish the release -core ci --were-go-for-launch +# Generate specific language +core build sdk --lang typescript + +# Preview without writing +core build sdk --dry-run ``` -See [ci command](../ci/) for release details. - -## Configuration - -Configure SDK generation in `.core/release.yaml`: - -```yaml -sdk: - # OpenAPI spec path (auto-detected if not set) - spec: api/openapi.yaml - - # Languages to generate - languages: - - typescript - - python - - go - - php - - # Output directory - output: sdk - - # Package naming - package: - name: my-api-sdk - - # Breaking change detection - diff: - enabled: true - fail_on_breaking: false # Warn but continue -``` +See [build sdk](../build/sdk/) for generation details. ## Spec Auto-Detection @@ -162,24 +100,7 @@ Core looks for OpenAPI specs in this order: 4. `docs/openapi.yaml` / `docs/openapi.json` 5. Laravel Scramble endpoint (`/docs/api.json`) -## Output Structure +## See Also -Generated SDKs are placed in language-specific directories: - -``` -sdk/ -├── typescript/ -│ ├── src/ -│ ├── package.json -│ └── tsconfig.json -├── python/ -│ ├── my_api_sdk/ -│ ├── setup.py -│ └── requirements.txt -├── go/ -│ ├── client.go -│ └── go.mod -└── php/ - ├── src/ - └── composer.json -``` +- [build sdk](../build/sdk/) - Generate SDKs from OpenAPI +- [ci command](../ci/) - Release workflow diff --git a/docs/cmd/vm/index.md b/docs/cmd/vm/index.md index 45052de..91afcef 100644 --- a/docs/cmd/vm/index.md +++ b/docs/cmd/vm/index.md @@ -34,9 +34,11 @@ core vm run --template [flags] |------|-------------| | `--template` | Use a template instead of image file | | `--var` | Set template variable (KEY=value) | -| `--memory` | Memory in MB (default: 4096) | -| `--cpus` | CPU count (default: 4) | -| `-d` | Run in background | +| `--name` | Name for the container | +| `--memory` | Memory in MB (default: 1024) | +| `--cpus` | CPU count (default: 1) | +| `--ssh-port` | SSH port for exec commands (default: 2222) | +| `-d` | Run in detached mode (background) | ## vm ps