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 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
78cb2b3507
commit
76872efbd7
4 changed files with 54 additions and 184 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 <pattern> [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 <repo> [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
|
||||
|
|
|
|||
|
|
@ -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 <command> [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
|
||||
|
|
|
|||
|
|
@ -34,9 +34,11 @@ core vm run --template <name> [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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue