From 35aaed2d26018d64a5a00775aeba88a73563c6fd Mon Sep 17 00:00:00 2001 From: Dmitrii Iutkin Date: Mon, 9 Nov 2026 16:18:09 +0200 Subject: [PATCH 1/6] docs: generate the command reference from the cobra tree docs/commands.md was hand-written and had drifted from the CLI: container, registry, object-storage, template, mcp, skills, status, doctor, version, the vm shortcuts and volume delete were missing. Instead of copying more text from --help and the per-command READMEs, render it from the command definitions themselves. - cmd/gen-docs + internal/verda-cli/docgen write docs/commands.md (index grouped as in verda --help, with beta tags) and docs/reference/.md (usage, aliases, flags, examples). Hidden and deprecated commands are skipped; output is deterministic (no dates, VERDA_* env stripped). - CommandGroups.Add also registers native cobra groups and a declaration rank, so the index keeps the group order, titles and command order of verda --help (cobra sorts Commands() in place). verda --help output is unchanged. - make docs regenerates; make docs.check fails when stale. A new Docs workflow (no paths-ignore) and the pre-commit hook run the check. - .gitattributes marks the generated files linguist-generated. - The env-var table moves to docs/guides/authentication.md and the scripting sections to docs/guides/scripting.md. The credential order stays only in verda auth --help, which docs/reference/auth.md renders. Co-Authored-By: Claude Opus 5.5 --- .ai/skills/new-command.md | 6 + .gitattributes | 2 + .github/workflows/docs.yml | 26 ++ AGENTS.md | 1 + CLAUDE.md | 4 + Makefile | 12 +- README.md | 4 +- cmd/gen-docs/main.go | 77 ++++ docs/guides/authentication.md | 35 ++ docs/guides/scripting.md | 41 +++ githooks/pre-commit | 12 + internal/verda-cli/cmd/auth/README.md | 2 +- internal/verda-cli/cmd/util/command_groups.go | 25 +- .../verda-cli/cmd/util/command_groups_test.go | 20 ++ internal/verda-cli/docgen/docgen.go | 337 ++++++++++++++++++ internal/verda-cli/docgen/docgen_test.go | 239 +++++++++++++ 16 files changed, 839 insertions(+), 4 deletions(-) create mode 100644 .gitattributes create mode 100644 .github/workflows/docs.yml create mode 100644 cmd/gen-docs/main.go create mode 100644 docs/guides/authentication.md create mode 100644 docs/guides/scripting.md create mode 100644 internal/verda-cli/docgen/docgen.go create mode 100644 internal/verda-cli/docgen/docgen_test.go diff --git a/.ai/skills/new-command.md b/.ai/skills/new-command.md index 4ed3b288..c63d153e 100644 --- a/.ai/skills/new-command.md +++ b/.ai/skills/new-command.md @@ -303,6 +303,12 @@ _, _ = fmt.Fprint(ioStreams.Out, content) The pager auto-detects: prints directly if content fits terminal, otherwise shows scrollable viewport. +### 13. Regenerate the Command Reference + +`docs/commands.md` and `docs/reference/` are generated from `Use`/`Short`/`Long`/`Example` and flags. Run +`make docs` after adding or changing a command and commit the result; `make docs.check` (CI and pre-commit) +fails while they are stale. Never hand-edit those files — put user-facing text in the command definition. + ## Dependencies - `cmdutil "github/verda-cloud/verda-cli/internal/verda-cli/cmd/util"` -- Factory, IOStreams, DebugJSON, helpers diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..f0add05b --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +docs/commands.md linguist-generated=true +docs/reference/** linguist-generated=true diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..3c28a784 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,26 @@ +name: Docs + +# No paths-ignore (unlike ci.yml): a docs-only PR that hand-edits generated +# command docs must still fail here. +on: + push: + branches: [main] + pull_request: + branches: [main, develop] + +jobs: + docs-check: + name: Command docs up to date + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v6 + + - name: Set up Go + uses: actions/setup-go@v6 + with: + go-version-file: go.mod + cache: true + + - name: Check generated command docs + run: make docs.check diff --git a/AGENTS.md b/AGENTS.md index 38bf1aa3..b10647a7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,6 +53,7 @@ Skipping these steps leads to pattern violations, broken dual-mode, and pricing - [ ] `make lint` passes with zero issues (do not rely on pre-commit to surface these) - [ ] `make test` passes (unit tests with -race; lint is the separate `make lint` item above) - [ ] `make fix.check` passes (run `make fix` to apply pending `go fix` modernizations) +- [ ] `make docs.check` passes (run `make docs` after changing a command; never hand-edit `docs/commands.md` or `docs/reference/`) - [ ] `--help` renders correctly for changed commands - [ ] Interactive and non-interactive modes both work - [ ] Interactive Selects pass `tui.WithShowHints(true)` so the hint bar renders diff --git a/CLAUDE.md b/CLAUDE.md index 9825a624..99821e1e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,6 +9,7 @@ make build # Build binary to ./bin/verda make test # Run all tests (go test -race) make lint # Lint only (golangci-lint); also run by pre-commit hooks make fix # Apply go fix modernizers; CI runs `make fix.check` +make docs # Regenerate docs/commands.md + docs/reference/ from cobra; CI runs `make docs.check` make pre-commit # Full pre-commit suite ``` @@ -20,6 +21,7 @@ Never use raw `go test ./...` — always `make test` (go test -race). Lint is se ``` cmd/verda/ # Entrypoint +cmd/gen-docs/ # `make docs`: writes docs/commands.md + docs/reference/ (generated, don't hand-edit) internal/verda-cli/ cmd/cmd.go # Root command, command groups cmd/util/ # Factory, IOStreams, helpers, pricing, hostname @@ -27,6 +29,7 @@ internal/verda-cli/ CLAUDE.md # Domain knowledge, gotchas, edge cases README.md # Usage examples, flags, architecture notes options/ # Global CLI options, credentials + docgen/ # Renders the command reference from the cobra tree internal/skills/ # Embedded AI skill files (go:embed) pkg/ # In-tree TUI core, log, version (formerly verdagostack) ``` @@ -167,6 +170,7 @@ make build # Must compile make test # Must pass (go test -race) make lint # Must pass (golangci-lint; also run by pre-commit hooks) make fix.check # Must pass (go fix modernizers; `make fix` applies them) +make docs.check # Must pass (generated command docs; `make docs` regenerates them) ``` **Never** report work as complete with lint failures outstanding. Fix them before the "done" message; don't defer to the pre-commit hook. See the "Go House Style" section above for the patterns that prevent the common hits. diff --git a/Makefile b/Makefile index cfecc09e..322e5b71 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ GOLANGCI_LINT := GOTOOLCHAIN=go$(GO_VERSION) go run github.com/golangci/golangci # Toolchain pinned because each Go release adds or removes fixers; the integration tag brings tests/integration into scope. GOFIX := GOTOOLCHAIN=go$(GO_VERSION) go fix -tags=integration -.PHONY: all build clean run.sandbox lint lint.fix security fix fix.check test test.integration test-s3-integration fmt changelog changelog.unreleased hooks.install pre-commit help +.PHONY: all build clean run.sandbox lint lint.fix security fix fix.check docs docs.check test test.integration test-s3-integration fmt changelog changelog.unreleased hooks.install pre-commit help ## Build ------------------------------------------------------------------- @@ -47,6 +47,16 @@ fix: ## Apply go fix modernizers fix.check: ## Fail if go fix has pending modernizations (CI) @$(GOFIX) -diff ./... || { echo "Pending go fix changes. Run 'make fix'"; exit 1; } +docs: ## Regenerate docs/commands.md and docs/reference/ from the cobra command tree + @go run ./cmd/gen-docs -out docs + +docs.check: ## Fail if generated command docs are stale (CI) + @tmp=$$(mktemp -d); trap 'rm -rf "$$tmp"' EXIT; \ + go run ./cmd/gen-docs -out "$$tmp" || exit 1; \ + if ! diff -u docs/commands.md "$$tmp/commands.md" || ! diff -ru docs/reference "$$tmp/reference"; then \ + echo "Command docs are stale. Run 'make docs'"; exit 1; \ + fi + test: ## Run all tests (with race detector) @go test -race -count=1 ./... diff --git a/README.md b/README.md index c85cf81a..0e339ecd 100644 --- a/README.md +++ b/README.md @@ -194,7 +194,9 @@ Multiple profiles are supported — switch with `verda auth use PROFILE`. | Doc | Description | |-----|-------------| -| [Command Reference](docs/commands.md) | Full list of commands, flags, and examples | +| [Command Reference](docs/commands.md) | Full list of commands, flags, and examples (generated by `make docs`) | +| [Authentication](docs/guides/authentication.md) | Credential resolution order and environment variables | +| [Scripting and Agent Mode](docs/guides/scripting.md) | Structured output, `--wait`, and `--agent` mode | | [Agent Error Format](docs/agent-errors.md) | Structured error specification for `--agent` mode | ## Contributing diff --git a/cmd/gen-docs/main.go b/cmd/gen-docs/main.go new file mode 100644 index 00000000..ea33bf06 --- /dev/null +++ b/cmd/gen-docs/main.go @@ -0,0 +1,77 @@ +// Copyright 2026 Verda Cloud Oy +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Command gen-docs writes docs/commands.md and docs/reference/ from the verda +// command tree. Run it via `make docs`; `make docs.check` fails when stale. +package main + +import ( + "bytes" + "flag" + "fmt" + "maps" + "os" + "path/filepath" + "slices" + "strings" + + "github.com/verda-cloud/verda-cli/internal/verda-cli/cmd" + cmdutil "github.com/verda-cloud/verda-cli/internal/verda-cli/cmd/util" + "github.com/verda-cloud/verda-cli/internal/verda-cli/docgen" +) + +func main() { + out := flag.String("out", "docs", "Docs directory to write commands.md and reference/ into") + flag.Parse() + if err := run(*out); err != nil { + fmt.Fprintln(os.Stderr, "gen-docs:", err) + os.Exit(1) + } +} + +func run(out string) error { + isolateEnv() + var discard bytes.Buffer + root, _ := cmd.NewRootCommand(cmdutil.IOStreams{In: &bytes.Buffer{}, Out: &discard, ErrOut: &discard}) + files, err := docgen.Generate(root) + if err != nil { + return err + } + // Stale pages of removed commands must not survive a regeneration. + if err := os.RemoveAll(filepath.Join(out, docgen.ReferenceDir)); err != nil { + return err + } + for _, name := range slices.Sorted(maps.Keys(files)) { + path := filepath.Join(out, filepath.FromSlash(name)) + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { //nolint:gosec // committed public docs + return err + } + if err := os.WriteFile(path, files[name], 0o644); err != nil { //nolint:gosec // committed public docs + return err + } + } + return nil +} + +// isolateEnv keeps output machine-independent: no inherited VERDA_* (so the +// batchjob gate stays off) and a fixed home for any path-derived defaults. +func isolateEnv() { + for _, kv := range os.Environ() { + if name, _, _ := strings.Cut(kv, "="); strings.HasPrefix(name, "VERDA_") { + _ = os.Unsetenv(name) + } + } + _ = os.Setenv("HOME", "/home/user") + _ = os.Setenv("VERDA_HOME", "/home/user/.verda") +} diff --git a/docs/guides/authentication.md b/docs/guides/authentication.md new file mode 100644 index 00000000..8142a323 --- /dev/null +++ b/docs/guides/authentication.md @@ -0,0 +1,35 @@ +# Authentication + +How the Verda CLI finds API credentials. For the `verda auth` commands themselves (`login`, `show`, `use`), see the +[auth reference](../reference/auth.md). + +## Credential Resolution Order + +Flags, environment variables, `~/.verda/config.yaml` and the credentials file are checked in a fixed order for each +credential, the credentials file path and the profile. `verda auth --help` lists that order. The +[auth reference](../reference/auth.md) shows the same text. + +## Environment Variables + +Pairs such as `VERDA_AUTH_CLIENT_ID` and `VERDA_CLIENT_ID` set the same value at different precedence. + +| Variable | Description | +|----------|-------------| +| `VERDA_CLIENT_ID` | API client ID | +| `VERDA_CLIENT_SECRET` | API client secret | +| `VERDA_AUTH_CLIENT_ID` | API client ID | +| `VERDA_AUTH_CLIENT_SECRET` | API client secret | +| `VERDA_AUTH_TOKEN` | Bearer token | +| `VERDA_PROFILE` | Credentials profile name | +| `VERDA_AUTH_PROFILE` | Credentials profile name | +| `VERDA_AUTH_CREDENTIALS_FILE` | Path to credentials file | +| `VERDA_SHARED_CREDENTIALS_FILE` | Path to credentials file | +| `VERDA_AGENT` | Enable agent mode (`1` or `true`) | +| `VERDA_HOME` | Base directory for config (default `~/.verda`) | + +```bash +# Use env vars for CI/CD pipelines +export VERDA_CLIENT_ID=your-client-id +export VERDA_CLIENT_SECRET=your-client-secret +verda vm list +``` diff --git a/docs/guides/scripting.md b/docs/guides/scripting.md new file mode 100644 index 00000000..1d5ab47a --- /dev/null +++ b/docs/guides/scripting.md @@ -0,0 +1,41 @@ +# Scripting and Agent Mode + +How to drive the Verda CLI from scripts, CI pipelines and AI agents. Every flag mentioned here is listed under +[Global Flags](../commands.md#global-flags) or on the command's [reference page](../commands.md). + +## Structured Output + +All list and describe commands support `--output json` and `--output yaml` for scripting: + +```bash +# Pipe to jq +verda vm list -o json | jq '.[].hostname' + +# YAML output +verda volume describe vol-123 -o yaml + +# Use in CI/CD scripts +INSTANCE_ID=$(verda vm list -o json | jq -r '.[0].id') +``` + +## Wait for Operations + +Async commands support `--wait` to poll until completion: + +```bash +verda vm create --hostname gpu-runner --wait --wait-timeout 10m +verda vm action --id abc-123 --wait +verda volume create --name data --size 500 --wait +``` + +## Agent Mode (Beta) + +The `--agent` flag optimizes CLI behavior for AI agents and scripts: + +```bash +verda --agent vm list # JSON output, no interactive picker +verda --agent vm create ... # structured errors for missing flags +verda --agent vm action --id X --action shutdown --yes # --yes is required for destructive actions +``` + +See [Agent Errors](../agent-errors.md) for the structured error format. diff --git a/githooks/pre-commit b/githooks/pre-commit index 10eee662..9c5b15fc 100755 --- a/githooks/pre-commit +++ b/githooks/pre-commit @@ -10,7 +10,16 @@ set -euo pipefail STAGED_GO=$(git diff --cached --name-only --diff-filter=ACM -- '*.go' || true) +# Generated docs go stale on any Go change (deletions included) or a hand edit. +DOCS_TRIGGER=$(git diff --cached --name-only -- '*.go' docs/commands.md docs/reference || true) +if [ -z "$DOCS_TRIGGER" ]; then + exit 0 +fi if [ -z "$STAGED_GO" ]; then + printf "pre-commit: checking generated command docs ...\n" + printf " make docs.check\n" + make --no-print-directory docs.check + printf "pre-commit: ok.\n" exit 0 fi @@ -26,6 +35,9 @@ go vet ./... printf " make fix.check\n" make --no-print-directory fix.check +printf " make docs.check\n" +make --no-print-directory docs.check + printf " make lint\n" make --no-print-directory lint diff --git a/internal/verda-cli/cmd/auth/README.md b/internal/verda-cli/cmd/auth/README.md index 4cd46e53..cc424058 100644 --- a/internal/verda-cli/cmd/auth/README.md +++ b/internal/verda-cli/cmd/auth/README.md @@ -58,7 +58,7 @@ Run `verda auth --help` for the full order in which flags, environment variables, `~/.verda/config.yaml` and the credentials file are checked, including how `login`, `use`, registry and object-storage differ. The environment variables are listed in -[docs/commands.md](../../../../docs/commands.md#environment-variables). +[the authentication guide](../../../../docs/guides/authentication.md#environment-variables). ### Explicit Profile Selection diff --git a/internal/verda-cli/cmd/util/command_groups.go b/internal/verda-cli/cmd/util/command_groups.go index 26d78479..1658accc 100644 --- a/internal/verda-cli/cmd/util/command_groups.go +++ b/internal/verda-cli/cmd/util/command_groups.go @@ -17,6 +17,7 @@ package util import ( "fmt" "slices" + "strconv" "strings" "github.com/spf13/cobra" @@ -35,13 +36,35 @@ type CommandGroup struct { // CommandGroups is an ordered list of command groups. type CommandGroups []CommandGroup -// Add registers every command in each group as a subcommand of c. +// orderAnnotation: declaration rank set by Add. Cobra sorts Commands() in +// place, so it is the only record of the order the grouped --help shows. +const orderAnnotation = "verda.order" + +// Add registers every command in each group as a subcommand of c, mirroring +// the groups as native cobra groups so docgen can read their order and titles. func (g CommandGroups) Add(c *cobra.Command) { + rank := 0 for _, group := range g { + c.AddGroup(&cobra.Group{ID: group.Message, Title: group.Message}) + for _, sub := range group.Commands { + sub.GroupID = group.Message + if sub.Annotations == nil { + sub.Annotations = map[string]string{} + } + sub.Annotations[orderAnnotation] = strconv.Itoa(rank) + rank++ + } c.AddCommand(group.Commands...) } } +// DeclarationOrder returns c's position in the CommandGroups that added it; +// ok is false for commands not added through CommandGroups.Add. +func DeclarationOrder(c *cobra.Command) (rank int, ok bool) { + rank, err := strconv.Atoi(c.Annotations[orderAnnotation]) + return rank, err == nil +} + // Has returns true if c belongs to any group. func (g CommandGroups) Has(c *cobra.Command) bool { for _, group := range g { diff --git a/internal/verda-cli/cmd/util/command_groups_test.go b/internal/verda-cli/cmd/util/command_groups_test.go index 6ef9b56e..b84cebfe 100644 --- a/internal/verda-cli/cmd/util/command_groups_test.go +++ b/internal/verda-cli/cmd/util/command_groups_test.go @@ -41,3 +41,23 @@ func TestSetUsageTemplate_TagAnnotation(t *testing.T) { t.Errorf("untagged command must not get a tag; got:\n%s", tmpl) } } + +func TestCommandGroupsAdd_NativeGroups(t *testing.T) { + t.Parallel() + auth := &cobra.Command{Use: "auth"} + vm := &cobra.Command{Use: "vm"} + root := &cobra.Command{Use: "verda"} + groups := CommandGroups{ + {Message: "Auth Commands:", Commands: []*cobra.Command{auth}}, + {Message: "VM Commands:", Commands: []*cobra.Command{vm}}, + } + groups.Add(root) + + got := root.Groups() + if len(got) != 2 || got[0].Title != "Auth Commands:" || got[1].Title != "VM Commands:" { + t.Fatalf("groups should keep declared order; got %+v", got) + } + if auth.GroupID != got[0].ID || vm.GroupID != got[1].ID { + t.Errorf("commands should carry their group ID; auth=%q vm=%q", auth.GroupID, vm.GroupID) + } +} diff --git a/internal/verda-cli/docgen/docgen.go b/internal/verda-cli/docgen/docgen.go new file mode 100644 index 00000000..fed69804 --- /dev/null +++ b/internal/verda-cli/docgen/docgen.go @@ -0,0 +1,337 @@ +// Copyright 2026 Verda Cloud Oy +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Package docgen renders the command reference (docs/commands.md and +// docs/reference/*.md) from the cobra command tree, so the docs carry the +// same text as --help and cannot drift from it. +package docgen + +import ( + "bytes" + "cmp" + "fmt" + "math" + "slices" + "strings" + + "github.com/spf13/cobra" + "github.com/spf13/pflag" + + cmdutil "github.com/verda-cloud/verda-cli/internal/verda-cli/cmd/util" +) + +const ( + // IndexFile is the grouped command index, relative to the docs dir. + IndexFile = "commands.md" + // ReferenceDir holds one page per top-level command, relative to the docs dir. + ReferenceDir = "reference" + + generatedHeader = "\n\n" + ungroupedTitle = "Additional Commands" + + indexIntro = `# Command Reference + +Every Verda CLI command, grouped as in ` + "`verda --help`" + `. Each entry links to its reference page with +usage, flags and examples. The pages are generated from the CLI's own help text. + +See also: [Authentication](guides/authentication.md) · [Scripting and agent mode](guides/scripting.md) · +[Agent error format](agent-errors.md) · [AI skills](ai-skills.md) + +` + + globalFlagsNote = "Global flags such as `--output`, `--agent` and `--debug` work with every command: " + + "see [Global Flags](../" + IndexFile + "#global-flags).\n" +) + +// Generate returns the rendered docs keyed by slash-separated path relative +// to the docs dir. Hidden, deprecated and help commands are left out. +func Generate(root *cobra.Command) (map[string][]byte, error) { + files := map[string][]byte{IndexFile: renderIndex(root)} + for _, top := range root.Commands() { + if top.IsAvailableCommand() { + files[pagePath(top)] = renderPage(root, top) + } + } + // Styled text would leak terminal escapes into Markdown. + for name, b := range files { + if bytes.ContainsRune(b, '\x1b') { + return nil, fmt.Errorf("%s: ANSI escape in command help text", name) + } + } + return files, nil +} + +type commandGroup struct { + title string + commands []*cobra.Command +} + +// groupedCommands: root.Groups() order; within a group, declaration order as +// in --help, then any undeclared commands by name. +func groupedCommands(root *cobra.Command) []commandGroup { + groups := make([]commandGroup, 0, len(root.Groups())+1) + byID := map[string]int{} + for _, g := range root.Groups() { + byID[g.ID] = len(groups) + groups = append(groups, commandGroup{title: strings.TrimSuffix(g.Title, ":")}) + } + ungrouped := commandGroup{title: ungroupedTitle} + for _, c := range root.Commands() { + if !c.IsAvailableCommand() { + continue + } + if i, ok := byID[c.GroupID]; ok { + groups[i].commands = append(groups[i].commands, c) + } else { + ungrouped.commands = append(ungrouped.commands, c) + } + } + if len(ungrouped.commands) > 0 { + groups = append(groups, ungrouped) + } + for i := range groups { + slices.SortStableFunc(groups[i].commands, func(a, b *cobra.Command) int { + return cmp.Compare(declarationRank(a), declarationRank(b)) + }) + } + return groups +} + +func declarationRank(c *cobra.Command) int { + if rank, ok := cmdutil.DeclarationOrder(c); ok { + return rank + } + return math.MaxInt +} + +func renderIndex(root *cobra.Command) []byte { + var b strings.Builder + b.WriteString(generatedHeader) + b.WriteString(indexIntro) + for _, g := range groupedCommands(root) { + if len(g.commands) == 0 { + continue + } + fmt.Fprintf(&b, "## %s\n\n| Command | Description |\n|---------|-------------|\n", g.title) + for _, top := range g.commands { + page := pagePath(top) + fmt.Fprintf(&b, "| [`%s`](%s)%s | %s |\n", top.CommandPath(), page, tagSuffix(top), tableCell(top.Short)) + for _, c := range descendants(top) { + fmt.Fprintf(&b, "| [`%s`](%s#%s) | %s |\n", c.CommandPath(), page, anchor(c), tableCell(c.Short)) + } + } + b.WriteString("\n") + } + b.WriteString("## Global Flags\n\n") + writeFence(&b, "text", visibleFlags(root.PersistentFlags(), nil).FlagUsages()) + return []byte(strings.TrimRight(b.String(), "\n") + "\n") +} + +func renderPage(root, top *cobra.Command) []byte { + var b strings.Builder + b.WriteString(generatedHeader) + fmt.Fprintf(&b, "# %s%s\n\n", top.CommandPath(), tagSuffix(top)) + writeCommand(&b, root, top) + subs := descendants(top) + if len(subs) > 0 { + b.WriteString("Subcommands:\n\n") + for _, c := range subs { + fmt.Fprintf(&b, "- [`%s`](#%s): %s\n", c.CommandPath(), anchor(c), escapeText(c.Short)) + } + b.WriteString("\n") + } + for _, c := range subs { + fmt.Fprintf(&b, "## %s\n\n", c.CommandPath()) + writeCommand(&b, root, c) + } + b.WriteString("---\n\n") + b.WriteString(globalFlagsNote) + return []byte(strings.TrimRight(b.String(), "\n") + "\n") +} + +func writeCommand(b *strings.Builder, root, c *cobra.Command) { + // LocalFlags/InheritedFlags merge parent persistent flags into c; UseLine's + // "[flags]" depends on that merge, so resolve flags before rendering usage. + local := visibleFlags(c.LocalFlags(), nil) + notGlobal := func(f *pflag.Flag) bool { return root.PersistentFlags().Lookup(f.Name) == nil } + inherited := visibleFlags(c.InheritedFlags(), notGlobal) + + b.WriteString(escapeText(c.Short) + "\n\n") + if c.Long != "" { + b.WriteString(renderLong(c.Long)) + } + // Group commands' Run only prints help; their subcommand list is the usage. + if c.Runnable() && !c.HasAvailableSubCommands() { + b.WriteString("**Usage**\n\n") + writeFence(b, "text", c.UseLine()) + } + if len(c.Aliases) > 0 { + b.WriteString("Aliases: `" + strings.Join(c.Aliases, "`, `") + "`\n\n") + } + if local.HasAvailableFlags() { + b.WriteString("**Flags**\n\n") + writeFence(b, "text", local.FlagUsages()) + } + if inherited.HasAvailableFlags() { + b.WriteString("**Inherited flags**\n\n") + writeFence(b, "text", inherited.FlagUsages()) + } + if c.Example != "" { + b.WriteString("**Examples**\n\n") + writeFence(b, "bash", dedent(c.Example)) + } +} + +// renderLong keeps prose as Markdown paragraphs and fences each run of +// indented lines, which GFM would otherwise merge into the paragraph. +func renderLong(s string) string { + lines := strings.Split(strings.TrimSpace(s), "\n") + var b strings.Builder + for i := 0; i < len(lines); { + j := i + 1 + if isIndented(lines[i]) { + for j < len(lines) && continuesCode(lines, j) { + j++ + } + writeFence(&b, "text", dedent(strings.Join(lines[i:j], "\n"))) + } else { + for j < len(lines) && !isIndented(lines[j]) { + j++ + } + writeProse(&b, lines[i:j]) + } + i = j + } + return b.String() +} + +// continuesCode: an indented line, or a blank line followed by more indented ones. +func continuesCode(lines []string, j int) bool { + for ; j < len(lines); j++ { + if strings.TrimSpace(lines[j]) != "" { + return isIndented(lines[j]) + } + } + return false +} + +func writeProse(b *strings.Builder, lines []string) { + text := strings.Trim(strings.Join(lines, "\n"), "\n ") + for line := range strings.SplitSeq(text, "\n") { + // Trailing double spaces would become hard line breaks. + line = escapeText(strings.TrimRight(line, " \t")) + if strings.HasPrefix(line, "#") { + line = `\` + line + } + b.WriteString(line + "\n") + } + b.WriteString("\n") +} + +func isIndented(line string) bool { + return line != "" && (line[0] == ' ' || line[0] == '\t') +} + +func dedent(s string) string { + lines := strings.Split(strings.Trim(s, "\n"), "\n") + minIndent := -1 + for _, line := range lines { + if strings.TrimSpace(line) == "" { + continue + } + if n := len(line) - len(strings.TrimLeft(line, " \t")); minIndent < 0 || n < minIndent { + minIndent = n + } + } + for i, line := range lines { + switch { + case strings.TrimSpace(line) == "": + lines[i] = "" + case minIndent > 0: + lines[i] = line[minIndent:] + } + } + return strings.Join(lines, "\n") +} + +// escapeText escapes HTML and emphasis characters outside `code spans`, so +// placeholders like survive GFM rendering. +func escapeText(s string) string { + parts := strings.Split(s, "`") + closed := len(parts)%2 == 1 + r := strings.NewReplacer("&", "&", "<", "<", ">", ">", "*", `\*`) + for i := range parts { + inCode := i%2 == 1 && (closed || i < len(parts)-1) + if !inCode { + parts[i] = r.Replace(parts[i]) + } + } + return strings.Join(parts, "`") +} + +// tableCell additionally escapes pipes, which split GFM cells even inside code spans. +func tableCell(s string) string { + return strings.ReplaceAll(escapeText(s), "|", `\|`) +} + +func writeFence(b *strings.Builder, lang, body string) { + fence := "```" + if strings.Contains(body, fence) { + fence = "~~~~" + } + lines := strings.Split(strings.TrimRight(body, " \n"), "\n") + for i := range lines { + lines[i] = strings.TrimRight(lines[i], " \t") + } + b.WriteString(fence + lang + "\n" + strings.Join(lines, "\n") + "\n" + fence + "\n\n") +} + +// visibleFlags copies the non-hidden flags (minus help) that pass keep. +func visibleFlags(fs *pflag.FlagSet, keep func(*pflag.Flag) bool) *pflag.FlagSet { + out := pflag.NewFlagSet("", pflag.ContinueOnError) + fs.VisitAll(func(f *pflag.Flag) { + if !f.Hidden && f.Name != "help" && (keep == nil || keep(f)) { + out.AddFlag(f) + } + }) + return out +} + +// descendants lists available subcommands depth-first, sorted by name. +func descendants(c *cobra.Command) []*cobra.Command { + var out []*cobra.Command + for _, sub := range c.Commands() { + if sub.IsAvailableCommand() { + out = append(out, sub) + out = append(out, descendants(sub)...) + } + } + return out +} + +func pagePath(top *cobra.Command) string { + return ReferenceDir + "/" + top.Name() + ".md" +} + +// anchor matches GitHub's heading slug for a "## verda " heading. +func anchor(c *cobra.Command) string { + return strings.ReplaceAll(strings.ToLower(c.CommandPath()), " ", "-") +} + +func tagSuffix(c *cobra.Command) string { + if tag := c.Annotations[cmdutil.TagAnnotation]; tag != "" { + return " (" + tag + ")" + } + return "" +} diff --git a/internal/verda-cli/docgen/docgen_test.go b/internal/verda-cli/docgen/docgen_test.go new file mode 100644 index 00000000..ad837f6e --- /dev/null +++ b/internal/verda-cli/docgen/docgen_test.go @@ -0,0 +1,239 @@ +// Copyright 2026 Verda Cloud Oy +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package docgen + +import ( + "bytes" + "maps" + "slices" + "strings" + "testing" + + "github.com/spf13/cobra" + + cmdutil "github.com/verda-cloud/verda-cli/internal/verda-cli/cmd/util" +) + +func newTestRoot() *cobra.Command { + run := func(*cobra.Command, []string) {} + root := &cobra.Command{Use: "verda"} + root.PersistentFlags().StringP("output", "o", "table", "Output format") + root.PersistentFlags().String("secret", "", "Hidden global flag") + _ = root.PersistentFlags().MarkHidden("secret") + + vm := &cobra.Command{Use: "vm", Short: "Manage virtual machines"} + vmList := &cobra.Command{Use: "list", Aliases: []string{"ls"}, Short: "List VMs", Run: run, + Example: " # All VMs\n verda vm list"} + vmList.Flags().String("status", "", "Filter by status") + vm.AddCommand(vmList) + + container := &cobra.Command{ + Use: "container", + Short: "Manage containers", + Annotations: map[string]string{cmdutil.TagAnnotation: "beta"}, + Long: "Deploy a with *.csv input.\n\nBash:\n source <(verda completion bash)\n\n # once:\n verda completion bash > /etc/x\n\nDone.", + } + create := &cobra.Command{Use: "create ", Short: "Create a | deployment", Run: run} + internal := &cobra.Command{Use: "internal", Short: "Hidden subcommand", Hidden: true, Run: run} + container.AddCommand(create, internal) + batchjob := &cobra.Command{Use: "batchjob", Short: "Hidden top-level", Hidden: true, Run: run} + + cmdutil.CommandGroups{ + {Message: "VM Commands:", Commands: []*cobra.Command{vm}}, + {Message: "Serverless Commands:", Commands: []*cobra.Command{container, batchjob}}, + }.Add(root) + return root +} + +func generate(t *testing.T) map[string]string { + t.Helper() + files, err := Generate(newTestRoot()) + if err != nil { + t.Fatalf("Generate: %v", err) + } + out := map[string]string{} + for name, b := range files { + out[name] = string(b) + } + return out +} + +func TestGenerate_Files(t *testing.T) { + t.Parallel() + got := slices.Sorted(maps.Keys(generate(t))) + want := []string{"commands.md", "reference/container.md", "reference/vm.md"} + if !slices.Equal(got, want) { + t.Errorf("files = %v, want %v (hidden commands get no page)", got, want) + } +} + +func TestGenerate_Index(t *testing.T) { + t.Parallel() + index := generate(t)[IndexFile] + + vmAt, serverlessAt := strings.Index(index, "## VM Commands"), strings.Index(index, "## Serverless Commands") + if vmAt < 0 || serverlessAt < vmAt { + t.Errorf("groups should follow declared order; got:\n%s", index) + } + for _, want := range []string{ + generatedHeader, + "| [`verda container`](reference/container.md) (beta) | Manage containers |", + "| [`verda vm list`](reference/vm.md#verda-vm-list) | List VMs |", + `Create a \| deployment`, + "-o, --output string", + } { + if !strings.Contains(index, want) { + t.Errorf("index missing %q; got:\n%s", want, index) + } + } + for _, unwanted := range []string{"batchjob", "internal", "--secret"} { + if strings.Contains(index, unwanted) { + t.Errorf("index must not mention hidden %q; got:\n%s", unwanted, index) + } + } +} + +// verda --help lists a group's commands as declared; the index must match, not sort them. +func TestGenerate_IndexKeepsDeclarationOrder(t *testing.T) { + t.Parallel() + run := func(*cobra.Command, []string) {} + root := &cobra.Command{Use: "verda"} + groups := cmdutil.CommandGroups{{Message: "VM Commands:", Commands: []*cobra.Command{ + {Use: "vm", Short: "Manage virtual machines", Run: run}, + {Use: "ssh", Short: "SSH into a VM", Run: run}, + }}} + groups.Add(root) + cmdutil.SetUsageTemplate(root, groups) + + files, err := Generate(root) + if err != nil { + t.Fatal(err) + } + index := string(files[IndexFile]) + vmAt, sshAt := strings.Index(index, "[`verda vm`]"), strings.Index(index, "[`verda ssh`]") + if vmAt < 0 || sshAt < vmAt { + t.Errorf("index should list vm before ssh, as declared; got:\n%s", index) + } +} + +func TestGenerate_Page(t *testing.T) { + t.Parallel() + files := generate(t) + page := files["reference/vm.md"] + for _, want := range []string{ + "# verda vm\n", + "- [`verda vm list`](#verda-vm-list): List VMs", + "## verda vm list\n", + "Aliases: `ls`", + "--status string", + "```bash\n# All VMs\nverda vm list\n```", + "../commands.md#global-flags", + } { + if !strings.Contains(page, want) { + t.Errorf("vm page missing %q; got:\n%s", want, page) + } + } + if strings.Contains(page, "-o, --output") { + t.Errorf("global flags belong on the index only; got:\n%s", page) + } + if strings.Contains(files["reference/container.md"], "internal") { + t.Errorf("hidden subcommand must be skipped") + } +} + +func TestGenerate_LongText(t *testing.T) { + t.Parallel() + page := generate(t)["reference/container.md"] + for _, want := range []string{ + "# verda container (beta)", + `Deploy a <name> with \*.csv input.`, + "```text\nsource <(verda completion bash)\n\n# once:\nverda completion bash > /etc/x\n```\n\nDone.", + } { + if !strings.Contains(page, want) { + t.Errorf("container page missing %q; got:\n%s", want, page) + } + } +} + +func TestGenerate_Deterministic(t *testing.T) { + t.Parallel() + first, err := Generate(newTestRoot()) + if err != nil { + t.Fatal(err) + } + second, err := Generate(newTestRoot()) + if err != nil { + t.Fatal(err) + } + if !maps.EqualFunc(first, second, bytes.Equal) { + t.Error("two runs over equal trees must produce identical output") + } +} + +// Rendering resolves (and so mutates) flag state; a rerun on the same tree must not differ. +func TestGenerate_IdempotentOnSameRoot(t *testing.T) { + t.Parallel() + root := newTestRoot() + first, err := Generate(root) + if err != nil { + t.Fatal(err) + } + second, err := Generate(root) + if err != nil { + t.Fatal(err) + } + if !maps.EqualFunc(first, second, bytes.Equal) { + t.Error("a second run over the same root must produce identical output") + } +} + +func TestGenerate_UsageShowsInheritedFlags(t *testing.T) { + t.Parallel() + root := &cobra.Command{Use: "verda"} + root.PersistentFlags().String("output", "table", "Output format") + root.AddCommand(&cobra.Command{Use: "locations", Short: "List locations", Run: func(*cobra.Command, []string) {}}) + files, err := Generate(root) + if err != nil { + t.Fatal(err) + } + if page := string(files["reference/locations.md"]); !strings.Contains(page, "verda locations [flags]") { + t.Errorf("usage should include [flags] from global flags, as --help does; got:\n%s", page) + } +} + +func TestGenerate_RejectsANSI(t *testing.T) { + t.Parallel() + root := &cobra.Command{Use: "verda"} + root.AddCommand(&cobra.Command{Use: "status", Short: "\x1b[1mStatus\x1b[0m", Run: func(*cobra.Command, []string) {}}) + if _, err := Generate(root); err == nil { + t.Error("expected an error for ANSI escapes in help text") + } +} + +func TestEscapeText(t *testing.T) { + t.Parallel() + tests := map[string]string{ + "plain": "plain", + "copy ": "copy <src> <dst>", + "run `verda ` now": "run `verda ` now", + "a & b * c": `a & b \* c`, + "unclosed `": "unclosed `<x>", + } + for in, want := range tests { + if got := escapeText(in); got != want { + t.Errorf("escapeText(%q) = %q, want %q", in, got, want) + } + } +} From 9957e710c647e410c187f5dbb7dfa436dee726cd Mon Sep 17 00:00:00 2001 From: Dmitrii Iutkin Date: Mon, 9 Nov 2026 18:16:42 +0200 Subject: [PATCH 2/6] docs: harden the command docs generator and hook - gen-docs builds the command tree under a throwaway HOME and VERDA_HOME that is removed after the run, instead of a fixed /home/user path. - docgen filters inherited flags by identity, so a group flag that shadows a global flag of the same name is listed, not dropped. - cmdutil.TagSuffix builds the " (beta)" suffix for both the root help and the generated docs. - The pre-commit hook runs make docs.check once, before the Go checks. - docgen uses one textLang constant for text fences. Co-Authored-By: Claude Opus 5.5 --- cmd/gen-docs/main.go | 21 +++++-- githooks/pre-commit | 13 ++-- internal/verda-cli/cmd/util/command_groups.go | 15 +++-- .../verda-cli/cmd/util/command_groups_test.go | 17 ++++++ internal/verda-cli/docgen/docgen.go | 25 ++++---- internal/verda-cli/docgen/docgen_test.go | 59 +++++++++++++++++++ 6 files changed, 117 insertions(+), 33 deletions(-) diff --git a/cmd/gen-docs/main.go b/cmd/gen-docs/main.go index ea33bf06..d050d3f6 100644 --- a/cmd/gen-docs/main.go +++ b/cmd/gen-docs/main.go @@ -41,7 +41,11 @@ func main() { } func run(out string) error { - isolateEnv() + cleanup, err := isolateEnv() + if err != nil { + return err + } + defer cleanup() var discard bytes.Buffer root, _ := cmd.NewRootCommand(cmdutil.IOStreams{In: &bytes.Buffer{}, Out: &discard, ErrOut: &discard}) files, err := docgen.Generate(root) @@ -64,14 +68,19 @@ func run(out string) error { return nil } -// isolateEnv keeps output machine-independent: no inherited VERDA_* (so the -// batchjob gate stays off) and a fixed home for any path-derived defaults. -func isolateEnv() { +// isolateEnv: no inherited VERDA_* (batchjob gate off) and a throwaway home, so building +// the tree can't touch a real config dir; docs.check catches any home-derived help text. +func isolateEnv() (cleanup func(), err error) { for _, kv := range os.Environ() { if name, _, _ := strings.Cut(kv, "="); strings.HasPrefix(name, "VERDA_") { _ = os.Unsetenv(name) } } - _ = os.Setenv("HOME", "/home/user") - _ = os.Setenv("VERDA_HOME", "/home/user/.verda") + home, err := os.MkdirTemp("", "verda-gen-docs-") + if err != nil { + return nil, err + } + _ = os.Setenv("HOME", home) + _ = os.Setenv("VERDA_HOME", filepath.Join(home, ".verda")) + return func() { _ = os.RemoveAll(home) }, nil } diff --git a/githooks/pre-commit b/githooks/pre-commit index 9c5b15fc..197caa4d 100755 --- a/githooks/pre-commit +++ b/githooks/pre-commit @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Pre-commit hook — fast checks on staged Go files. +# Pre-commit hook — checks generated command docs, then fast checks on staged Go files. # # Install (once per clone): # make hooks.install @@ -15,10 +15,12 @@ DOCS_TRIGGER=$(git diff --cached --name-only -- '*.go' docs/commands.md docs/ref if [ -z "$DOCS_TRIGGER" ]; then exit 0 fi + +printf "pre-commit: checking generated command docs ...\n" +printf " make docs.check\n" +make --no-print-directory docs.check + if [ -z "$STAGED_GO" ]; then - printf "pre-commit: checking generated command docs ...\n" - printf " make docs.check\n" - make --no-print-directory docs.check printf "pre-commit: ok.\n" exit 0 fi @@ -35,9 +37,6 @@ go vet ./... printf " make fix.check\n" make --no-print-directory fix.check -printf " make docs.check\n" -make --no-print-directory docs.check - printf " make lint\n" make --no-print-directory lint diff --git a/internal/verda-cli/cmd/util/command_groups.go b/internal/verda-cli/cmd/util/command_groups.go index 1658accc..81d5c0be 100644 --- a/internal/verda-cli/cmd/util/command_groups.go +++ b/internal/verda-cli/cmd/util/command_groups.go @@ -27,6 +27,15 @@ import ( // next to its name in the grouped root help. Set via cmd.Annotations. const TagAnnotation = "verda.tag" +// TagSuffix returns " ()" for a command with TagAnnotation, else "". +// The root help and the generated docs both use it, so they cannot drift. +func TagSuffix(c *cobra.Command) string { + if tag := c.Annotations[TagAnnotation]; tag != "" { + return " (" + tag + ")" + } + return "" +} + // CommandGroup represents a logical group of subcommands with a heading message. type CommandGroup struct { Message string @@ -110,11 +119,7 @@ func SetUsageTemplate(cmd *cobra.Command, groups CommandGroups) { if c.Hidden { continue } - name := c.Name() - if tag := c.Annotations[TagAnnotation]; tag != "" { - name += " (" + tag + ")" - } - fmt.Fprintf(&b, " %-18s %s\n", name, c.Short) + fmt.Fprintf(&b, " %-18s %s\n", c.Name()+TagSuffix(c), c.Short) } b.WriteString("\n") } diff --git a/internal/verda-cli/cmd/util/command_groups_test.go b/internal/verda-cli/cmd/util/command_groups_test.go index b84cebfe..1eaddbc1 100644 --- a/internal/verda-cli/cmd/util/command_groups_test.go +++ b/internal/verda-cli/cmd/util/command_groups_test.go @@ -42,6 +42,23 @@ func TestSetUsageTemplate_TagAnnotation(t *testing.T) { } } +func TestTagSuffix(t *testing.T) { + t.Parallel() + tests := map[string]struct { + cmd *cobra.Command + want string + }{ + "tagged": {&cobra.Command{Use: "s3", Annotations: map[string]string{TagAnnotation: "beta"}}, " (beta)"}, + "other annotations": {&cobra.Command{Use: "vm", Annotations: map[string]string{"x": "y"}}, ""}, + "no annotations": {&cobra.Command{Use: "vm"}, ""}, + } + for name, tc := range tests { + if got := TagSuffix(tc.cmd); got != tc.want { + t.Errorf("%s: TagSuffix = %q, want %q", name, got, tc.want) + } + } +} + func TestCommandGroupsAdd_NativeGroups(t *testing.T) { t.Parallel() auth := &cobra.Command{Use: "auth"} diff --git a/internal/verda-cli/docgen/docgen.go b/internal/verda-cli/docgen/docgen.go index fed69804..dacee4f2 100644 --- a/internal/verda-cli/docgen/docgen.go +++ b/internal/verda-cli/docgen/docgen.go @@ -39,6 +39,7 @@ const ( generatedHeader = "\n\n" ungroupedTitle = "Additional Commands" + textLang = "text" indexIntro = `# Command Reference @@ -126,7 +127,7 @@ func renderIndex(root *cobra.Command) []byte { fmt.Fprintf(&b, "## %s\n\n| Command | Description |\n|---------|-------------|\n", g.title) for _, top := range g.commands { page := pagePath(top) - fmt.Fprintf(&b, "| [`%s`](%s)%s | %s |\n", top.CommandPath(), page, tagSuffix(top), tableCell(top.Short)) + fmt.Fprintf(&b, "| [`%s`](%s)%s | %s |\n", top.CommandPath(), page, cmdutil.TagSuffix(top), tableCell(top.Short)) for _, c := range descendants(top) { fmt.Fprintf(&b, "| [`%s`](%s#%s) | %s |\n", c.CommandPath(), page, anchor(c), tableCell(c.Short)) } @@ -134,14 +135,14 @@ func renderIndex(root *cobra.Command) []byte { b.WriteString("\n") } b.WriteString("## Global Flags\n\n") - writeFence(&b, "text", visibleFlags(root.PersistentFlags(), nil).FlagUsages()) + writeFence(&b, textLang, visibleFlags(root.PersistentFlags(), nil).FlagUsages()) return []byte(strings.TrimRight(b.String(), "\n") + "\n") } func renderPage(root, top *cobra.Command) []byte { var b strings.Builder b.WriteString(generatedHeader) - fmt.Fprintf(&b, "# %s%s\n\n", top.CommandPath(), tagSuffix(top)) + fmt.Fprintf(&b, "# %s%s\n\n", top.CommandPath(), cmdutil.TagSuffix(top)) writeCommand(&b, root, top) subs := descendants(top) if len(subs) > 0 { @@ -164,7 +165,8 @@ func writeCommand(b *strings.Builder, root, c *cobra.Command) { // LocalFlags/InheritedFlags merge parent persistent flags into c; UseLine's // "[flags]" depends on that merge, so resolve flags before rendering usage. local := visibleFlags(c.LocalFlags(), nil) - notGlobal := func(f *pflag.Flag) bool { return root.PersistentFlags().Lookup(f.Name) == nil } + // By identity: a group flag may shadow a global flag of the same name. + notGlobal := func(f *pflag.Flag) bool { return root.PersistentFlags().Lookup(f.Name) != f } inherited := visibleFlags(c.InheritedFlags(), notGlobal) b.WriteString(escapeText(c.Short) + "\n\n") @@ -174,18 +176,18 @@ func writeCommand(b *strings.Builder, root, c *cobra.Command) { // Group commands' Run only prints help; their subcommand list is the usage. if c.Runnable() && !c.HasAvailableSubCommands() { b.WriteString("**Usage**\n\n") - writeFence(b, "text", c.UseLine()) + writeFence(b, textLang, c.UseLine()) } if len(c.Aliases) > 0 { b.WriteString("Aliases: `" + strings.Join(c.Aliases, "`, `") + "`\n\n") } if local.HasAvailableFlags() { b.WriteString("**Flags**\n\n") - writeFence(b, "text", local.FlagUsages()) + writeFence(b, textLang, local.FlagUsages()) } if inherited.HasAvailableFlags() { b.WriteString("**Inherited flags**\n\n") - writeFence(b, "text", inherited.FlagUsages()) + writeFence(b, textLang, inherited.FlagUsages()) } if c.Example != "" { b.WriteString("**Examples**\n\n") @@ -204,7 +206,7 @@ func renderLong(s string) string { for j < len(lines) && continuesCode(lines, j) { j++ } - writeFence(&b, "text", dedent(strings.Join(lines[i:j], "\n"))) + writeFence(&b, textLang, dedent(strings.Join(lines[i:j], "\n"))) } else { for j < len(lines) && !isIndented(lines[j]) { j++ @@ -328,10 +330,3 @@ func pagePath(top *cobra.Command) string { func anchor(c *cobra.Command) string { return strings.ReplaceAll(strings.ToLower(c.CommandPath()), " ", "-") } - -func tagSuffix(c *cobra.Command) string { - if tag := c.Annotations[cmdutil.TagAnnotation]; tag != "" { - return " (" + tag + ")" - } - return "" -} diff --git a/internal/verda-cli/docgen/docgen_test.go b/internal/verda-cli/docgen/docgen_test.go index ad837f6e..2698da2f 100644 --- a/internal/verda-cli/docgen/docgen_test.go +++ b/internal/verda-cli/docgen/docgen_test.go @@ -22,6 +22,7 @@ import ( "testing" "github.com/spf13/cobra" + "github.com/spf13/pflag" cmdutil "github.com/verda-cloud/verda-cli/internal/verda-cli/cmd/util" ) @@ -213,6 +214,64 @@ func TestGenerate_UsageShowsInheritedFlags(t *testing.T) { } } +// registryLsSection renders a tree whose registry group declares persistent flags +// via addFlags, and returns the "verda registry ls" section of its page. +func registryLsSection(t *testing.T, addFlags func(*pflag.FlagSet)) string { + t.Helper() + root := &cobra.Command{Use: "verda"} + root.PersistentFlags().StringP("output", "o", "table", "Output format") + registry := &cobra.Command{Use: "registry", Short: "Manage the registry"} + addFlags(registry.PersistentFlags()) + ls := &cobra.Command{Use: "ls", Short: "List repositories", Run: func(*cobra.Command, []string) {}} + ls.Flags().Bool("all", false, "Include empty repositories") + registry.AddCommand(ls) + root.AddCommand(registry) + + files, err := Generate(root) + if err != nil { + t.Fatal(err) + } + page := string(files["reference/registry.md"]) + _, section, ok := strings.Cut(page, "## verda registry ls\n") + if !ok { + t.Fatalf("page has no registry ls section; got:\n%s", page) + } + return section +} + +func TestGenerate_InheritedFlags(t *testing.T) { + t.Parallel() + section := registryLsSection(t, func(fs *pflag.FlagSet) { + fs.String("project", "", "Registry project") + }) + local, inherited, ok := strings.Cut(section, "**Inherited flags**") + if !ok { + t.Fatalf("a group's persistent flag should be listed under Inherited flags; got:\n%s", section) + } + if !strings.Contains(local, "--all") { + t.Errorf("local flag --all should be listed under Flags; got:\n%s", section) + } + if !strings.Contains(inherited, "--project string") { + t.Errorf("group flag --project should be listed under Inherited flags; got:\n%s", section) + } + if strings.Contains(section, "-o, --output") { + t.Errorf("global flags belong on the index only; got:\n%s", section) + } +} + +// Cobra gives a subcommand the nearest parent's flag of a name, so a group flag +// that shadows a global one is not the global flag and must be listed. +func TestGenerate_InheritedFlagShadowsGlobal(t *testing.T) { + t.Parallel() + section := registryLsSection(t, func(fs *pflag.FlagSet) { + fs.String("output", "json", "Registry output format") + }) + _, inherited, ok := strings.Cut(section, "**Inherited flags**") + if !ok || !strings.Contains(inherited, `Registry output format (default "json")`) { + t.Errorf("the group's --output should be listed under Inherited flags; got:\n%s", section) + } +} + func TestGenerate_RejectsANSI(t *testing.T) { t.Parallel() root := &cobra.Command{Use: "verda"} From ecdc8c1137c5564d86eaeeed4476462180554074 Mon Sep 17 00:00:00 2001 From: Dmitrii Iutkin Date: Tue, 10 Nov 2026 10:07:01 +0200 Subject: [PATCH 3/6] docs: regenerate the command reference at release, not per PR The docs on main described unreleased commands and flags, because every PR had to regenerate them. The release job now runs `make docs VERSION=vX.Y.Z` before it commits the changelog and tags, so each tag carries docs that match its code. docs/commands.md names the release it matches. - release.yml: generate docs, commit them with the changelog (`git add -A` on docs/reference drops pages of removed commands) - gen-docs: -version flag (vX.Y.Z), stamped into the index intro - drop the docs.yml workflow, `make docs.check` and the pre-commit docs gate - TestRun builds the docs from the real command tree in `make test`, twice, so a generator failure or environment-derived help text shows up in CI - contributor docs: generated files stay out of PRs; `make docs` is a preview Co-Authored-By: Claude Opus 5.5 --- .ai/skills/new-command.md | 8 +-- .github/workflows/docs.yml | 26 ------- .github/workflows/release.yml | 15 ++-- AGENTS.md | 2 +- CLAUDE.md | 5 +- Makefile | 13 +--- README.md | 2 +- cmd/gen-docs/main.go | 17 +++-- cmd/gen-docs/main_test.go | 92 ++++++++++++++++++++++++ githooks/pre-commit | 13 +--- internal/verda-cli/docgen/docgen.go | 25 +++++-- internal/verda-cli/docgen/docgen_test.go | 46 +++++++++--- 12 files changed, 183 insertions(+), 81 deletions(-) delete mode 100644 .github/workflows/docs.yml create mode 100644 cmd/gen-docs/main_test.go diff --git a/.ai/skills/new-command.md b/.ai/skills/new-command.md index c63d153e..afa666d6 100644 --- a/.ai/skills/new-command.md +++ b/.ai/skills/new-command.md @@ -303,11 +303,11 @@ _, _ = fmt.Fprint(ioStreams.Out, content) The pager auto-detects: prints directly if content fits terminal, otherwise shows scrollable viewport. -### 13. Regenerate the Command Reference +### 13. Command Reference Text -`docs/commands.md` and `docs/reference/` are generated from `Use`/`Short`/`Long`/`Example` and flags. Run -`make docs` after adding or changing a command and commit the result; `make docs.check` (CI and pre-commit) -fails while they are stale. Never hand-edit those files — put user-facing text in the command definition. +`docs/commands.md` and `docs/reference/` are generated from `Use`/`Short`/`Long`/`Example` and flags, and the +release job regenerates and commits them, so the published docs match the released binary. Put user-facing text +in the command definition. `make docs` previews the output locally; leave the generated files out of your PR. ## Dependencies diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml deleted file mode 100644 index 3c28a784..00000000 --- a/.github/workflows/docs.yml +++ /dev/null @@ -1,26 +0,0 @@ -name: Docs - -# No paths-ignore (unlike ci.yml): a docs-only PR that hand-edits generated -# command docs must still fail here. -on: - push: - branches: [main] - pull_request: - branches: [main, develop] - -jobs: - docs-check: - name: Command docs up to date - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v6 - - - name: Set up Go - uses: actions/setup-go@v6 - with: - go-version-file: go.mod - cache: true - - - name: Check generated command docs - run: make docs.check diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8f9cc8bd..de7b86b0 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -56,16 +56,23 @@ jobs: # which is the bug this fixes. --tag labels the unreleased section with VERSION. git-cliff --unreleased --tag ${{ github.event.inputs.version }} --strip header -o RELEASE_NOTES.md - - name: Commit changelog and tag release + # Before the commit/tag step: the tag must carry docs that match its code, + # and a generator failure must stop the release before anything is pushed. + - name: Generate command docs + run: make docs VERSION=${{ github.event.inputs.version }} + + - name: Commit changelog and docs, tag release run: | VERSION="${{ github.event.inputs.version }}" git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" git remote set-url origin https://x-access-token:${{ secrets.RELEASE_TOKEN }}@github.com/${{ github.repository }} - git add CHANGELOG.md - # [skip ci]: the changelog already reflects this release; no need to + git add CHANGELOG.md docs/commands.md + # -A: pages of removed commands are deleted, not left behind. + git add -A docs/reference + # [skip ci]: changelog and docs already reflect this release; no need to # re-trigger the Update Changelog workflow on this push. - git commit -m "chore(release): update changelog for ${VERSION} [skip ci]" + git commit -m "chore(release): update changelog and command docs for ${VERSION} [skip ci]" git tag "${VERSION}" git push origin main --tags diff --git a/AGENTS.md b/AGENTS.md index b10647a7..7bcd1962 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,7 +53,7 @@ Skipping these steps leads to pattern violations, broken dual-mode, and pricing - [ ] `make lint` passes with zero issues (do not rely on pre-commit to surface these) - [ ] `make test` passes (unit tests with -race; lint is the separate `make lint` item above) - [ ] `make fix.check` passes (run `make fix` to apply pending `go fix` modernizations) -- [ ] `make docs.check` passes (run `make docs` after changing a command; never hand-edit `docs/commands.md` or `docs/reference/`) +- [ ] `docs/commands.md` and `docs/reference/` unchanged in the diff (the release job regenerates them; user-facing text lives in the command's `Short`/`Long`/`Example`) - [ ] `--help` renders correctly for changed commands - [ ] Interactive and non-interactive modes both work - [ ] Interactive Selects pass `tui.WithShowHints(true)` so the hint bar renders diff --git a/CLAUDE.md b/CLAUDE.md index 99821e1e..f371efab 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,7 +9,7 @@ make build # Build binary to ./bin/verda make test # Run all tests (go test -race) make lint # Lint only (golangci-lint); also run by pre-commit hooks make fix # Apply go fix modernizers; CI runs `make fix.check` -make docs # Regenerate docs/commands.md + docs/reference/ from cobra; CI runs `make docs.check` +make docs # Preview docs/commands.md + docs/reference/; the release job regenerates and commits them make pre-commit # Full pre-commit suite ``` @@ -21,7 +21,7 @@ Never use raw `go test ./...` — always `make test` (go test -race). Lint is se ``` cmd/verda/ # Entrypoint -cmd/gen-docs/ # `make docs`: writes docs/commands.md + docs/reference/ (generated, don't hand-edit) +cmd/gen-docs/ # `make docs`: writes docs/commands.md + docs/reference/ (release-owned output) internal/verda-cli/ cmd/cmd.go # Root command, command groups cmd/util/ # Factory, IOStreams, helpers, pricing, hostname @@ -170,7 +170,6 @@ make build # Must compile make test # Must pass (go test -race) make lint # Must pass (golangci-lint; also run by pre-commit hooks) make fix.check # Must pass (go fix modernizers; `make fix` applies them) -make docs.check # Must pass (generated command docs; `make docs` regenerates them) ``` **Never** report work as complete with lint failures outstanding. Fix them before the "done" message; don't defer to the pre-commit hook. See the "Go House Style" section above for the patterns that prevent the common hits. diff --git a/Makefile b/Makefile index 322e5b71..453f4fcd 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ GOLANGCI_LINT := GOTOOLCHAIN=go$(GO_VERSION) go run github.com/golangci/golangci # Toolchain pinned because each Go release adds or removes fixers; the integration tag brings tests/integration into scope. GOFIX := GOTOOLCHAIN=go$(GO_VERSION) go fix -tags=integration -.PHONY: all build clean run.sandbox lint lint.fix security fix fix.check docs docs.check test test.integration test-s3-integration fmt changelog changelog.unreleased hooks.install pre-commit help +.PHONY: all build clean run.sandbox lint lint.fix security fix fix.check docs test test.integration test-s3-integration fmt changelog changelog.unreleased hooks.install pre-commit help ## Build ------------------------------------------------------------------- @@ -47,15 +47,8 @@ fix: ## Apply go fix modernizers fix.check: ## Fail if go fix has pending modernizations (CI) @$(GOFIX) -diff ./... || { echo "Pending go fix changes. Run 'make fix'"; exit 1; } -docs: ## Regenerate docs/commands.md and docs/reference/ from the cobra command tree - @go run ./cmd/gen-docs -out docs - -docs.check: ## Fail if generated command docs are stale (CI) - @tmp=$$(mktemp -d); trap 'rm -rf "$$tmp"' EXIT; \ - go run ./cmd/gen-docs -out "$$tmp" || exit 1; \ - if ! diff -u docs/commands.md "$$tmp/commands.md" || ! diff -ru docs/reference "$$tmp/reference"; then \ - echo "Command docs are stale. Run 'make docs'"; exit 1; \ - fi +docs: ## Regenerate docs/commands.md and docs/reference/ (release job passes VERSION=vX.Y.Z) + @go run ./cmd/gen-docs -out docs $(if $(VERSION),-version $(VERSION)) test: ## Run all tests (with race detector) @go test -race -count=1 ./... diff --git a/README.md b/README.md index 0e339ecd..88cf5416 100644 --- a/README.md +++ b/README.md @@ -194,7 +194,7 @@ Multiple profiles are supported — switch with `verda auth use PROFILE`. | Doc | Description | |-----|-------------| -| [Command Reference](docs/commands.md) | Full list of commands, flags, and examples (generated by `make docs`) | +| [Command Reference](docs/commands.md) | Full list of commands, flags, and examples (regenerated at each release) | | [Authentication](docs/guides/authentication.md) | Credential resolution order and environment variables | | [Scripting and Agent Mode](docs/guides/scripting.md) | Structured output, `--wait`, and `--agent` mode | | [Agent Error Format](docs/agent-errors.md) | Structured error specification for `--agent` mode | diff --git a/cmd/gen-docs/main.go b/cmd/gen-docs/main.go index d050d3f6..31d9f57c 100644 --- a/cmd/gen-docs/main.go +++ b/cmd/gen-docs/main.go @@ -13,7 +13,7 @@ // limitations under the License. // Command gen-docs writes docs/commands.md and docs/reference/ from the verda -// command tree. Run it via `make docs`; `make docs.check` fails when stale. +// command tree. The release job runs it via `make docs VERSION=vX.Y.Z`. package main import ( @@ -23,6 +23,7 @@ import ( "maps" "os" "path/filepath" + "regexp" "slices" "strings" @@ -31,16 +32,22 @@ import ( "github.com/verda-cloud/verda-cli/internal/verda-cli/docgen" ) +var releaseVersion = regexp.MustCompile(`^v\d+\.\d+\.\d+$`) + func main() { out := flag.String("out", "docs", "Docs directory to write commands.md and reference/ into") + version := flag.String("version", "", "Release the docs match, e.g. v1.2.3 (optional)") flag.Parse() - if err := run(*out); err != nil { + if err := run(*out, *version); err != nil { fmt.Fprintln(os.Stderr, "gen-docs:", err) os.Exit(1) } } -func run(out string) error { +func run(out, version string) error { + if version != "" && !releaseVersion.MatchString(version) { + return fmt.Errorf("-version %q: want vX.Y.Z", version) + } cleanup, err := isolateEnv() if err != nil { return err @@ -48,7 +55,7 @@ func run(out string) error { defer cleanup() var discard bytes.Buffer root, _ := cmd.NewRootCommand(cmdutil.IOStreams{In: &bytes.Buffer{}, Out: &discard, ErrOut: &discard}) - files, err := docgen.Generate(root) + files, err := docgen.Generate(root, version) if err != nil { return err } @@ -69,7 +76,7 @@ func run(out string) error { } // isolateEnv: no inherited VERDA_* (batchjob gate off) and a throwaway home, so building -// the tree can't touch a real config dir; docs.check catches any home-derived help text. +// the tree can't touch a real config dir; TestRun catches any home-derived help text. func isolateEnv() (cleanup func(), err error) { for _, kv := range os.Environ() { if name, _, _ := strings.Cut(kv, "="); strings.HasPrefix(name, "VERDA_") { diff --git a/cmd/gen-docs/main_test.go b/cmd/gen-docs/main_test.go new file mode 100644 index 00000000..2fc54bb0 --- /dev/null +++ b/cmd/gen-docs/main_test.go @@ -0,0 +1,92 @@ +// Copyright 2026 Verda Cloud Oy +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package main + +import ( + "bytes" + "os" + "path/filepath" + "strings" + "testing" +) + +// TestRun builds the docs from the real command tree, as the release job does, so a +// generator failure surfaces in CI rather than first in a release. +func TestRun(t *testing.T) { + // t.Setenv restores what isolateEnv overwrites. + t.Setenv("HOME", t.TempDir()) + t.Setenv("VERDA_HOME", t.TempDir()) + + first, second := t.TempDir(), t.TempDir() + for _, dir := range []string{first, second} { + if err := run(dir, "v1.2.3"); err != nil { + t.Fatalf("run: %v", err) + } + } + + index := readFile(t, filepath.Join(first, "commands.md")) + if !strings.Contains(index, "This reference matches verda v1.2.3.") { + t.Errorf("commands.md does not name the release; got:\n%s", index) + } + readFile(t, filepath.Join(first, "reference", "vm.md")) + + // Each run gets a fresh temp home, so any home-derived help text differs between runs. + for _, name := range listFiles(t, first) { + a, b := readFile(t, filepath.Join(first, name)), readFile(t, filepath.Join(second, name)) + if a != b { + t.Errorf("%s differs between runs; help text must not depend on the environment", name) + } + } +} + +func TestRun_RejectsBadVersion(t *testing.T) { + for _, version := range []string{"1.2.3", "v1.2", "v1.2.3-rc1", "latest"} { + if err := run(t.TempDir(), version); err == nil { + t.Errorf("run(%q) = nil, want an error", version) + } + } +} + +func readFile(t *testing.T, path string) string { + t.Helper() + b, err := os.ReadFile(path) //nolint:gosec // test temp dir + if err != nil { + t.Fatal(err) + } + if bytes.ContainsRune(b, '\x1b') { + t.Errorf("%s contains an ANSI escape", path) + } + return string(b) +} + +func listFiles(t *testing.T, root string) []string { + t.Helper() + var names []string + err := filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error { + if err != nil || d.IsDir() { + return err + } + rel, err := filepath.Rel(root, path) + names = append(names, rel) + return err + }) + if err != nil { + t.Fatal(err) + } + if len(names) < 2 { + t.Fatalf("got %d generated files, want an index and reference pages", len(names)) + } + return names +} diff --git a/githooks/pre-commit b/githooks/pre-commit index 197caa4d..10eee662 100755 --- a/githooks/pre-commit +++ b/githooks/pre-commit @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Pre-commit hook — checks generated command docs, then fast checks on staged Go files. +# Pre-commit hook — fast checks on staged Go files. # # Install (once per clone): # make hooks.install @@ -10,18 +10,7 @@ set -euo pipefail STAGED_GO=$(git diff --cached --name-only --diff-filter=ACM -- '*.go' || true) -# Generated docs go stale on any Go change (deletions included) or a hand edit. -DOCS_TRIGGER=$(git diff --cached --name-only -- '*.go' docs/commands.md docs/reference || true) -if [ -z "$DOCS_TRIGGER" ]; then - exit 0 -fi - -printf "pre-commit: checking generated command docs ...\n" -printf " make docs.check\n" -make --no-print-directory docs.check - if [ -z "$STAGED_GO" ]; then - printf "pre-commit: ok.\n" exit 0 fi diff --git a/internal/verda-cli/docgen/docgen.go b/internal/verda-cli/docgen/docgen.go index dacee4f2..37990c20 100644 --- a/internal/verda-cli/docgen/docgen.go +++ b/internal/verda-cli/docgen/docgen.go @@ -37,7 +37,7 @@ const ( // ReferenceDir holds one page per top-level command, relative to the docs dir. ReferenceDir = "reference" - generatedHeader = "\n\n" + generatedHeader = "\n\n" ungroupedTitle = "Additional Commands" textLang = "text" @@ -46,19 +46,25 @@ const ( Every Verda CLI command, grouped as in ` + "`verda --help`" + `. Each entry links to its reference page with usage, flags and examples. The pages are generated from the CLI's own help text. +%s + See also: [Authentication](guides/authentication.md) · [Scripting and agent mode](guides/scripting.md) · [Agent error format](agent-errors.md) · [AI skills](ai-skills.md) ` + olderReleases = "For an older release, open `docs/commands.md` at that release's " + + "[tag](https://github.com/verda-cloud/verda-cli/tags)." + globalFlagsNote = "Global flags such as `--output`, `--agent` and `--debug` work with every command: " + "see [Global Flags](../" + IndexFile + "#global-flags).\n" ) // Generate returns the rendered docs keyed by slash-separated path relative -// to the docs dir. Hidden, deprecated and help commands are left out. -func Generate(root *cobra.Command) (map[string][]byte, error) { - files := map[string][]byte{IndexFile: renderIndex(root)} +// to the docs dir. Hidden, deprecated and help commands are left out. version +// (e.g. "v1.2.3") names the release the docs match; empty leaves it unnamed. +func Generate(root *cobra.Command, version string) (map[string][]byte, error) { + files := map[string][]byte{IndexFile: renderIndex(root, version)} for _, top := range root.Commands() { if top.IsAvailableCommand() { files[pagePath(top)] = renderPage(root, top) @@ -116,10 +122,10 @@ func declarationRank(c *cobra.Command) int { return math.MaxInt } -func renderIndex(root *cobra.Command) []byte { +func renderIndex(root *cobra.Command, version string) []byte { var b strings.Builder b.WriteString(generatedHeader) - b.WriteString(indexIntro) + fmt.Fprintf(&b, indexIntro, releaseNote(version)) for _, g := range groupedCommands(root) { if len(g.commands) == 0 { continue @@ -139,6 +145,13 @@ func renderIndex(root *cobra.Command) []byte { return []byte(strings.TrimRight(b.String(), "\n") + "\n") } +func releaseNote(version string) string { + if version == "" { + return "This reference is regenerated at each release and matches the latest one. " + olderReleases + } + return "This reference matches verda " + version + ". " + olderReleases +} + func renderPage(root, top *cobra.Command) []byte { var b strings.Builder b.WriteString(generatedHeader) diff --git a/internal/verda-cli/docgen/docgen_test.go b/internal/verda-cli/docgen/docgen_test.go index 2698da2f..c33dee17 100644 --- a/internal/verda-cli/docgen/docgen_test.go +++ b/internal/verda-cli/docgen/docgen_test.go @@ -60,7 +60,7 @@ func newTestRoot() *cobra.Command { func generate(t *testing.T) map[string]string { t.Helper() - files, err := Generate(newTestRoot()) + files, err := Generate(newTestRoot(), "") if err != nil { t.Fatalf("Generate: %v", err) } @@ -106,6 +106,34 @@ func TestGenerate_Index(t *testing.T) { } } +func TestGenerate_IndexNamesRelease(t *testing.T) { + t.Parallel() + tests := []struct { + version, want, unwanted string + }{ + {version: "v1.2.3", want: "This reference matches verda v1.2.3.", unwanted: "matches the latest one"}, + {version: "", want: "regenerated at each release and matches the latest one", unwanted: "matches verda v"}, + } + for _, tt := range tests { + files, err := Generate(newTestRoot(), tt.version) + if err != nil { + t.Fatalf("Generate(%q): %v", tt.version, err) + } + index := string(files[IndexFile]) + for _, want := range []string{tt.want, olderReleases} { + if !strings.Contains(index, want) { + t.Errorf("version %q: index missing %q; got:\n%s", tt.version, want, index) + } + } + if strings.Contains(index, tt.unwanted) { + t.Errorf("version %q: index must not contain %q", tt.version, tt.unwanted) + } + if strings.Contains(string(files["reference/vm.md"]), "v1.2.3") { + t.Errorf("version %q: only the index names the release", tt.version) + } + } +} + // verda --help lists a group's commands as declared; the index must match, not sort them. func TestGenerate_IndexKeepsDeclarationOrder(t *testing.T) { t.Parallel() @@ -118,7 +146,7 @@ func TestGenerate_IndexKeepsDeclarationOrder(t *testing.T) { groups.Add(root) cmdutil.SetUsageTemplate(root, groups) - files, err := Generate(root) + files, err := Generate(root, "") if err != nil { t.Fatal(err) } @@ -170,11 +198,11 @@ func TestGenerate_LongText(t *testing.T) { func TestGenerate_Deterministic(t *testing.T) { t.Parallel() - first, err := Generate(newTestRoot()) + first, err := Generate(newTestRoot(), "") if err != nil { t.Fatal(err) } - second, err := Generate(newTestRoot()) + second, err := Generate(newTestRoot(), "") if err != nil { t.Fatal(err) } @@ -187,11 +215,11 @@ func TestGenerate_Deterministic(t *testing.T) { func TestGenerate_IdempotentOnSameRoot(t *testing.T) { t.Parallel() root := newTestRoot() - first, err := Generate(root) + first, err := Generate(root, "") if err != nil { t.Fatal(err) } - second, err := Generate(root) + second, err := Generate(root, "") if err != nil { t.Fatal(err) } @@ -205,7 +233,7 @@ func TestGenerate_UsageShowsInheritedFlags(t *testing.T) { root := &cobra.Command{Use: "verda"} root.PersistentFlags().String("output", "table", "Output format") root.AddCommand(&cobra.Command{Use: "locations", Short: "List locations", Run: func(*cobra.Command, []string) {}}) - files, err := Generate(root) + files, err := Generate(root, "") if err != nil { t.Fatal(err) } @@ -227,7 +255,7 @@ func registryLsSection(t *testing.T, addFlags func(*pflag.FlagSet)) string { registry.AddCommand(ls) root.AddCommand(registry) - files, err := Generate(root) + files, err := Generate(root, "") if err != nil { t.Fatal(err) } @@ -276,7 +304,7 @@ func TestGenerate_RejectsANSI(t *testing.T) { t.Parallel() root := &cobra.Command{Use: "verda"} root.AddCommand(&cobra.Command{Use: "status", Short: "\x1b[1mStatus\x1b[0m", Run: func(*cobra.Command, []string) {}}) - if _, err := Generate(root); err == nil { + if _, err := Generate(root, ""); err == nil { t.Error("expected an error for ANSI escapes in help text") } } From 5048491b2e33483125c73e1e8646c020fce334a4 Mon Sep 17 00:00:00 2001 From: Dmitrii Iutkin Date: Tue, 10 Nov 2026 10:18:45 +0200 Subject: [PATCH 4/6] docs: stamp the release version on every generated page Committed command docs come only from the release job, which always has a version, so the version is now required: gen-docs rejects a missing or malformed -version and `make docs` requires VERSION, like `make changelog`. Every page carries the version under its title, since readers often land on a reference page directly. Co-Authored-By: Claude Opus 5.5 --- .ai/skills/new-command.md | 3 +- CLAUDE.md | 2 +- Makefile | 9 ++-- cmd/gen-docs/main.go | 8 +--- cmd/gen-docs/main_test.go | 12 +++-- internal/verda-cli/docgen/docgen.go | 39 ++++++++--------- internal/verda-cli/docgen/docgen_test.go | 56 +++++++++++------------- 7 files changed, 63 insertions(+), 66 deletions(-) diff --git a/.ai/skills/new-command.md b/.ai/skills/new-command.md index afa666d6..e700593e 100644 --- a/.ai/skills/new-command.md +++ b/.ai/skills/new-command.md @@ -307,7 +307,8 @@ The pager auto-detects: prints directly if content fits terminal, otherwise show `docs/commands.md` and `docs/reference/` are generated from `Use`/`Short`/`Long`/`Example` and flags, and the release job regenerates and commits them, so the published docs match the released binary. Put user-facing text -in the command definition. `make docs` previews the output locally; leave the generated files out of your PR. +in the command definition and leave the generated files out of your PR; `TestRun` in `cmd/gen-docs` checks the +generator on every `make test`. ## Dependencies diff --git a/CLAUDE.md b/CLAUDE.md index f371efab..a8f81bea 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,7 +9,7 @@ make build # Build binary to ./bin/verda make test # Run all tests (go test -race) make lint # Lint only (golangci-lint); also run by pre-commit hooks make fix # Apply go fix modernizers; CI runs `make fix.check` -make docs # Preview docs/commands.md + docs/reference/; the release job regenerates and commits them +make docs VERSION=vX.Y.Z # Release job only: generates docs/commands.md + docs/reference/ for that version make pre-commit # Full pre-commit suite ``` diff --git a/Makefile b/Makefile index 453f4fcd..abc90f22 100644 --- a/Makefile +++ b/Makefile @@ -47,9 +47,6 @@ fix: ## Apply go fix modernizers fix.check: ## Fail if go fix has pending modernizations (CI) @$(GOFIX) -diff ./... || { echo "Pending go fix changes. Run 'make fix'"; exit 1; } -docs: ## Regenerate docs/commands.md and docs/reference/ (release job passes VERSION=vX.Y.Z) - @go run ./cmd/gen-docs -out docs $(if $(VERSION),-version $(VERSION)) - test: ## Run all tests (with race detector) @go test -race -count=1 ./... @@ -78,6 +75,12 @@ endif changelog.unreleased: ## Regenerate CHANGELOG.md with pending commits under [Unreleased] @git-cliff -o CHANGELOG.md +docs: ## Generate docs/commands.md and docs/reference/ for a release (requires VERSION, e.g. make docs VERSION=v1.0.0) +ifndef VERSION + $(error VERSION is required. Usage: make docs VERSION=v1.0.0) +endif + @go run ./cmd/gen-docs -out docs -version $(VERSION) + ## Git Hooks --------------------------------------------------------------- hooks.install: ## Configure git to use githooks/ as the hooks directory diff --git a/cmd/gen-docs/main.go b/cmd/gen-docs/main.go index 31d9f57c..c7b02358 100644 --- a/cmd/gen-docs/main.go +++ b/cmd/gen-docs/main.go @@ -23,7 +23,6 @@ import ( "maps" "os" "path/filepath" - "regexp" "slices" "strings" @@ -32,11 +31,9 @@ import ( "github.com/verda-cloud/verda-cli/internal/verda-cli/docgen" ) -var releaseVersion = regexp.MustCompile(`^v\d+\.\d+\.\d+$`) - func main() { out := flag.String("out", "docs", "Docs directory to write commands.md and reference/ into") - version := flag.String("version", "", "Release the docs match, e.g. v1.2.3 (optional)") + version := flag.String("version", "", "Release the docs describe, e.g. v1.2.3 (required)") flag.Parse() if err := run(*out, *version); err != nil { fmt.Fprintln(os.Stderr, "gen-docs:", err) @@ -45,9 +42,6 @@ func main() { } func run(out, version string) error { - if version != "" && !releaseVersion.MatchString(version) { - return fmt.Errorf("-version %q: want vX.Y.Z", version) - } cleanup, err := isolateEnv() if err != nil { return err diff --git a/cmd/gen-docs/main_test.go b/cmd/gen-docs/main_test.go index 2fc54bb0..f2b92fa1 100644 --- a/cmd/gen-docs/main_test.go +++ b/cmd/gen-docs/main_test.go @@ -37,7 +37,7 @@ func TestRun(t *testing.T) { } index := readFile(t, filepath.Join(first, "commands.md")) - if !strings.Contains(index, "This reference matches verda v1.2.3.") { + if !strings.Contains(index, "> Verda CLI **v1.2.3**") { t.Errorf("commands.md does not name the release; got:\n%s", index) } readFile(t, filepath.Join(first, "reference", "vm.md")) @@ -52,11 +52,17 @@ func TestRun(t *testing.T) { } func TestRun_RejectsBadVersion(t *testing.T) { - for _, version := range []string{"1.2.3", "v1.2", "v1.2.3-rc1", "latest"} { - if err := run(t.TempDir(), version); err == nil { + t.Setenv("HOME", t.TempDir()) + t.Setenv("VERDA_HOME", t.TempDir()) + out := t.TempDir() + for _, version := range []string{"", "latest"} { + if err := run(out, version); err == nil { t.Errorf("run(%q) = nil, want an error", version) } } + if entries, _ := os.ReadDir(out); len(entries) > 0 { + t.Errorf("a rejected run must write nothing; got %d entries", len(entries)) + } } func readFile(t *testing.T, path string) string { diff --git a/internal/verda-cli/docgen/docgen.go b/internal/verda-cli/docgen/docgen.go index 37990c20..9a1c45f4 100644 --- a/internal/verda-cli/docgen/docgen.go +++ b/internal/verda-cli/docgen/docgen.go @@ -22,6 +22,7 @@ import ( "cmp" "fmt" "math" + "regexp" "slices" "strings" @@ -40,34 +41,34 @@ const ( generatedHeader = "\n\n" ungroupedTitle = "Additional Commands" textLang = "text" + tagsURL = "https://github.com/verda-cloud/verda-cli/tags" - indexIntro = `# Command Reference - -Every Verda CLI command, grouped as in ` + "`verda --help`" + `. Each entry links to its reference page with + indexTitle = "Command Reference" + indexIntro = `Every Verda CLI command, grouped as in ` + "`verda --help`" + `. Each entry links to its reference page with usage, flags and examples. The pages are generated from the CLI's own help text. -%s - See also: [Authentication](guides/authentication.md) · [Scripting and agent mode](guides/scripting.md) · [Agent error format](agent-errors.md) · [AI skills](ai-skills.md) ` - olderReleases = "For an older release, open `docs/commands.md` at that release's " + - "[tag](https://github.com/verda-cloud/verda-cli/tags)." - globalFlagsNote = "Global flags such as `--output`, `--agent` and `--debug` work with every command: " + "see [Global Flags](../" + IndexFile + "#global-flags).\n" ) +var releaseVersion = regexp.MustCompile(`^v\d+\.\d+\.\d+$`) + // Generate returns the rendered docs keyed by slash-separated path relative // to the docs dir. Hidden, deprecated and help commands are left out. version -// (e.g. "v1.2.3") names the release the docs match; empty leaves it unnamed. +// is the release the docs describe (vX.Y.Z); every page names it. func Generate(root *cobra.Command, version string) (map[string][]byte, error) { + if !releaseVersion.MatchString(version) { + return nil, fmt.Errorf("version %q: want vX.Y.Z", version) + } files := map[string][]byte{IndexFile: renderIndex(root, version)} for _, top := range root.Commands() { if top.IsAvailableCommand() { - files[pagePath(top)] = renderPage(root, top) + files[pagePath(top)] = renderPage(root, top, version) } } // Styled text would leak terminal escapes into Markdown. @@ -124,8 +125,8 @@ func declarationRank(c *cobra.Command) int { func renderIndex(root *cobra.Command, version string) []byte { var b strings.Builder - b.WriteString(generatedHeader) - fmt.Fprintf(&b, indexIntro, releaseNote(version)) + writeTitle(&b, indexTitle, version) + b.WriteString(indexIntro) for _, g := range groupedCommands(root) { if len(g.commands) == 0 { continue @@ -145,17 +146,15 @@ func renderIndex(root *cobra.Command, version string) []byte { return []byte(strings.TrimRight(b.String(), "\n") + "\n") } -func releaseNote(version string) string { - if version == "" { - return "This reference is regenerated at each release and matches the latest one. " + olderReleases - } - return "This reference matches verda " + version + ". " + olderReleases +// writeTitle: the version line sits under every H1, since readers often land on a page directly. +func writeTitle(b *strings.Builder, title, version string) { + b.WriteString(generatedHeader) + fmt.Fprintf(b, "# %s\n\n> Verda CLI **%s** · [other versions](%s)\n\n", title, version, tagsURL) } -func renderPage(root, top *cobra.Command) []byte { +func renderPage(root, top *cobra.Command, version string) []byte { var b strings.Builder - b.WriteString(generatedHeader) - fmt.Fprintf(&b, "# %s%s\n\n", top.CommandPath(), cmdutil.TagSuffix(top)) + writeTitle(&b, top.CommandPath()+cmdutil.TagSuffix(top), version) writeCommand(&b, root, top) subs := descendants(top) if len(subs) > 0 { diff --git a/internal/verda-cli/docgen/docgen_test.go b/internal/verda-cli/docgen/docgen_test.go index c33dee17..64a46b5d 100644 --- a/internal/verda-cli/docgen/docgen_test.go +++ b/internal/verda-cli/docgen/docgen_test.go @@ -58,9 +58,11 @@ func newTestRoot() *cobra.Command { return root } +const testVersion = "v1.2.3" + func generate(t *testing.T) map[string]string { t.Helper() - files, err := Generate(newTestRoot(), "") + files, err := Generate(newTestRoot(), testVersion) if err != nil { t.Fatalf("Generate: %v", err) } @@ -106,30 +108,22 @@ func TestGenerate_Index(t *testing.T) { } } -func TestGenerate_IndexNamesRelease(t *testing.T) { +func TestGenerate_EveryPageNamesVersion(t *testing.T) { t.Parallel() - tests := []struct { - version, want, unwanted string - }{ - {version: "v1.2.3", want: "This reference matches verda v1.2.3.", unwanted: "matches the latest one"}, - {version: "", want: "regenerated at each release and matches the latest one", unwanted: "matches verda v"}, - } - for _, tt := range tests { - files, err := Generate(newTestRoot(), tt.version) - if err != nil { - t.Fatalf("Generate(%q): %v", tt.version, err) - } - index := string(files[IndexFile]) - for _, want := range []string{tt.want, olderReleases} { - if !strings.Contains(index, want) { - t.Errorf("version %q: index missing %q; got:\n%s", tt.version, want, index) - } + const want = "> Verda CLI **" + testVersion + "** · [other versions](" + tagsURL + ")" + for name, page := range generate(t) { + lines := strings.SplitN(page, "\n", 6) + if len(lines) < 5 || !strings.HasPrefix(lines[2], "# ") || lines[4] != want { + t.Errorf("%s: want the version line right under the H1; got:\n%s", name, strings.Join(lines, "\n")) } - if strings.Contains(index, tt.unwanted) { - t.Errorf("version %q: index must not contain %q", tt.version, tt.unwanted) - } - if strings.Contains(string(files["reference/vm.md"]), "v1.2.3") { - t.Errorf("version %q: only the index names the release", tt.version) + } +} + +func TestGenerate_RejectsBadVersion(t *testing.T) { + t.Parallel() + for _, version := range []string{"", "1.2.3", "v1.2", "v1.2.3-rc1", "latest"} { + if _, err := Generate(newTestRoot(), version); err == nil { + t.Errorf("Generate(%q) = nil error, want one", version) } } } @@ -146,7 +140,7 @@ func TestGenerate_IndexKeepsDeclarationOrder(t *testing.T) { groups.Add(root) cmdutil.SetUsageTemplate(root, groups) - files, err := Generate(root, "") + files, err := Generate(root, testVersion) if err != nil { t.Fatal(err) } @@ -198,11 +192,11 @@ func TestGenerate_LongText(t *testing.T) { func TestGenerate_Deterministic(t *testing.T) { t.Parallel() - first, err := Generate(newTestRoot(), "") + first, err := Generate(newTestRoot(), testVersion) if err != nil { t.Fatal(err) } - second, err := Generate(newTestRoot(), "") + second, err := Generate(newTestRoot(), testVersion) if err != nil { t.Fatal(err) } @@ -215,11 +209,11 @@ func TestGenerate_Deterministic(t *testing.T) { func TestGenerate_IdempotentOnSameRoot(t *testing.T) { t.Parallel() root := newTestRoot() - first, err := Generate(root, "") + first, err := Generate(root, testVersion) if err != nil { t.Fatal(err) } - second, err := Generate(root, "") + second, err := Generate(root, testVersion) if err != nil { t.Fatal(err) } @@ -233,7 +227,7 @@ func TestGenerate_UsageShowsInheritedFlags(t *testing.T) { root := &cobra.Command{Use: "verda"} root.PersistentFlags().String("output", "table", "Output format") root.AddCommand(&cobra.Command{Use: "locations", Short: "List locations", Run: func(*cobra.Command, []string) {}}) - files, err := Generate(root, "") + files, err := Generate(root, testVersion) if err != nil { t.Fatal(err) } @@ -255,7 +249,7 @@ func registryLsSection(t *testing.T, addFlags func(*pflag.FlagSet)) string { registry.AddCommand(ls) root.AddCommand(registry) - files, err := Generate(root, "") + files, err := Generate(root, testVersion) if err != nil { t.Fatal(err) } @@ -304,7 +298,7 @@ func TestGenerate_RejectsANSI(t *testing.T) { t.Parallel() root := &cobra.Command{Use: "verda"} root.AddCommand(&cobra.Command{Use: "status", Short: "\x1b[1mStatus\x1b[0m", Run: func(*cobra.Command, []string) {}}) - if _, err := Generate(root, ""); err == nil { + if _, err := Generate(root, testVersion); err == nil { t.Error("expected an error for ANSI escapes in help text") } } From f2b15bb8fba4cc3ab14366f0b80e0adc31e364c8 Mon Sep 17 00:00:00 2001 From: Dmitrii Iutkin Date: Tue, 10 Nov 2026 10:43:07 +0200 Subject: [PATCH 5/6] docs: tighten the docs generator tests and fix guide claims - auth guide: the published auth page is the v1.10.0 text, which lists a shorter order without config.yaml; say so instead of claiming the guide and the page match - scripting guide: point "reference page" at the index that links them - gen-docs: drop the -out flag; only `docs` was ever passed - tests: reuse IndexFile/ReferenceDir, let generate() take a root, merge the two determinism tests, drop an ANSI check Generate already does Co-Authored-By: Claude Opus 5.5 --- Makefile | 2 +- cmd/gen-docs/main.go | 3 +- cmd/gen-docs/main_test.go | 12 ++--- docs/guides/authentication.md | 5 +- docs/guides/scripting.md | 3 +- internal/verda-cli/docgen/docgen_test.go | 64 ++++++------------------ 6 files changed, 28 insertions(+), 61 deletions(-) diff --git a/Makefile b/Makefile index abc90f22..2218a2e1 100644 --- a/Makefile +++ b/Makefile @@ -79,7 +79,7 @@ docs: ## Generate docs/commands.md and docs/reference/ for a release (requires V ifndef VERSION $(error VERSION is required. Usage: make docs VERSION=v1.0.0) endif - @go run ./cmd/gen-docs -out docs -version $(VERSION) + @go run ./cmd/gen-docs -version $(VERSION) ## Git Hooks --------------------------------------------------------------- diff --git a/cmd/gen-docs/main.go b/cmd/gen-docs/main.go index c7b02358..48038beb 100644 --- a/cmd/gen-docs/main.go +++ b/cmd/gen-docs/main.go @@ -32,10 +32,9 @@ import ( ) func main() { - out := flag.String("out", "docs", "Docs directory to write commands.md and reference/ into") version := flag.String("version", "", "Release the docs describe, e.g. v1.2.3 (required)") flag.Parse() - if err := run(*out, *version); err != nil { + if err := run("docs", *version); err != nil { fmt.Fprintln(os.Stderr, "gen-docs:", err) os.Exit(1) } diff --git a/cmd/gen-docs/main_test.go b/cmd/gen-docs/main_test.go index f2b92fa1..7b387d2f 100644 --- a/cmd/gen-docs/main_test.go +++ b/cmd/gen-docs/main_test.go @@ -15,17 +15,18 @@ package main import ( - "bytes" "os" "path/filepath" "strings" "testing" + + "github.com/verda-cloud/verda-cli/internal/verda-cli/docgen" ) // TestRun builds the docs from the real command tree, as the release job does, so a // generator failure surfaces in CI rather than first in a release. func TestRun(t *testing.T) { - // t.Setenv restores what isolateEnv overwrites. + // t.Setenv restores HOME and VERDA_HOME; other VERDA_* that isolateEnv unsets stay unset. t.Setenv("HOME", t.TempDir()) t.Setenv("VERDA_HOME", t.TempDir()) @@ -36,11 +37,11 @@ func TestRun(t *testing.T) { } } - index := readFile(t, filepath.Join(first, "commands.md")) + index := readFile(t, filepath.Join(first, docgen.IndexFile)) if !strings.Contains(index, "> Verda CLI **v1.2.3**") { t.Errorf("commands.md does not name the release; got:\n%s", index) } - readFile(t, filepath.Join(first, "reference", "vm.md")) + readFile(t, filepath.Join(first, docgen.ReferenceDir, "vm.md")) // Each run gets a fresh temp home, so any home-derived help text differs between runs. for _, name := range listFiles(t, first) { @@ -71,9 +72,6 @@ func readFile(t *testing.T, path string) string { if err != nil { t.Fatal(err) } - if bytes.ContainsRune(b, '\x1b') { - t.Errorf("%s contains an ANSI escape", path) - } return string(b) } diff --git a/docs/guides/authentication.md b/docs/guides/authentication.md index 8142a323..109c93da 100644 --- a/docs/guides/authentication.md +++ b/docs/guides/authentication.md @@ -6,8 +6,9 @@ How the Verda CLI finds API credentials. For the `verda auth` commands themselve ## Credential Resolution Order Flags, environment variables, `~/.verda/config.yaml` and the credentials file are checked in a fixed order for each -credential, the credentials file path and the profile. `verda auth --help` lists that order. The -[auth reference](../reference/auth.md) shows the same text. +credential, the credentials file path and the profile. `verda auth --help` and the +[auth reference](../reference/auth.md) list that order for releases after v1.10.0; up to v1.10.0 they print a +shorter list that leaves out `config.yaml`. ## Environment Variables diff --git a/docs/guides/scripting.md b/docs/guides/scripting.md index 1d5ab47a..b05f6b9f 100644 --- a/docs/guides/scripting.md +++ b/docs/guides/scripting.md @@ -1,7 +1,8 @@ # Scripting and Agent Mode How to drive the Verda CLI from scripts, CI pipelines and AI agents. Every flag mentioned here is listed under -[Global Flags](../commands.md#global-flags) or on the command's [reference page](../commands.md). +[Global Flags](../commands.md#global-flags) or on the command's reference page, linked from the +[command index](../commands.md). ## Structured Output diff --git a/internal/verda-cli/docgen/docgen_test.go b/internal/verda-cli/docgen/docgen_test.go index 64a46b5d..27752e9f 100644 --- a/internal/verda-cli/docgen/docgen_test.go +++ b/internal/verda-cli/docgen/docgen_test.go @@ -15,7 +15,6 @@ package docgen import ( - "bytes" "maps" "slices" "strings" @@ -60,9 +59,9 @@ func newTestRoot() *cobra.Command { const testVersion = "v1.2.3" -func generate(t *testing.T) map[string]string { +func generate(t *testing.T, root *cobra.Command) map[string]string { t.Helper() - files, err := Generate(newTestRoot(), testVersion) + files, err := Generate(root, testVersion) if err != nil { t.Fatalf("Generate: %v", err) } @@ -75,8 +74,8 @@ func generate(t *testing.T) map[string]string { func TestGenerate_Files(t *testing.T) { t.Parallel() - got := slices.Sorted(maps.Keys(generate(t))) - want := []string{"commands.md", "reference/container.md", "reference/vm.md"} + got := slices.Sorted(maps.Keys(generate(t, newTestRoot()))) + want := []string{IndexFile, "reference/container.md", "reference/vm.md"} if !slices.Equal(got, want) { t.Errorf("files = %v, want %v (hidden commands get no page)", got, want) } @@ -84,7 +83,7 @@ func TestGenerate_Files(t *testing.T) { func TestGenerate_Index(t *testing.T) { t.Parallel() - index := generate(t)[IndexFile] + index := generate(t, newTestRoot())[IndexFile] vmAt, serverlessAt := strings.Index(index, "## VM Commands"), strings.Index(index, "## Serverless Commands") if vmAt < 0 || serverlessAt < vmAt { @@ -111,7 +110,7 @@ func TestGenerate_Index(t *testing.T) { func TestGenerate_EveryPageNamesVersion(t *testing.T) { t.Parallel() const want = "> Verda CLI **" + testVersion + "** · [other versions](" + tagsURL + ")" - for name, page := range generate(t) { + for name, page := range generate(t, newTestRoot()) { lines := strings.SplitN(page, "\n", 6) if len(lines) < 5 || !strings.HasPrefix(lines[2], "# ") || lines[4] != want { t.Errorf("%s: want the version line right under the H1; got:\n%s", name, strings.Join(lines, "\n")) @@ -140,11 +139,7 @@ func TestGenerate_IndexKeepsDeclarationOrder(t *testing.T) { groups.Add(root) cmdutil.SetUsageTemplate(root, groups) - files, err := Generate(root, testVersion) - if err != nil { - t.Fatal(err) - } - index := string(files[IndexFile]) + index := generate(t, root)[IndexFile] vmAt, sshAt := strings.Index(index, "[`verda vm`]"), strings.Index(index, "[`verda ssh`]") if vmAt < 0 || sshAt < vmAt { t.Errorf("index should list vm before ssh, as declared; got:\n%s", index) @@ -153,7 +148,7 @@ func TestGenerate_IndexKeepsDeclarationOrder(t *testing.T) { func TestGenerate_Page(t *testing.T) { t.Parallel() - files := generate(t) + files := generate(t, newTestRoot()) page := files["reference/vm.md"] for _, want := range []string{ "# verda vm\n", @@ -178,7 +173,7 @@ func TestGenerate_Page(t *testing.T) { func TestGenerate_LongText(t *testing.T) { t.Parallel() - page := generate(t)["reference/container.md"] + page := generate(t, newTestRoot())["reference/container.md"] for _, want := range []string{ "# verda container (beta)", `Deploy a <name> with \*.csv input.`, @@ -190,34 +185,15 @@ func TestGenerate_LongText(t *testing.T) { } } +// Rendering resolves (and so mutates) flag state, so a rerun on the same root is checked too. func TestGenerate_Deterministic(t *testing.T) { - t.Parallel() - first, err := Generate(newTestRoot(), testVersion) - if err != nil { - t.Fatal(err) - } - second, err := Generate(newTestRoot(), testVersion) - if err != nil { - t.Fatal(err) - } - if !maps.EqualFunc(first, second, bytes.Equal) { - t.Error("two runs over equal trees must produce identical output") - } -} - -// Rendering resolves (and so mutates) flag state; a rerun on the same tree must not differ. -func TestGenerate_IdempotentOnSameRoot(t *testing.T) { t.Parallel() root := newTestRoot() - first, err := Generate(root, testVersion) - if err != nil { - t.Fatal(err) - } - second, err := Generate(root, testVersion) - if err != nil { - t.Fatal(err) + first := generate(t, root) + if !maps.Equal(first, generate(t, newTestRoot())) { + t.Error("two runs over equal trees must produce identical output") } - if !maps.EqualFunc(first, second, bytes.Equal) { + if !maps.Equal(first, generate(t, root)) { t.Error("a second run over the same root must produce identical output") } } @@ -227,11 +203,7 @@ func TestGenerate_UsageShowsInheritedFlags(t *testing.T) { root := &cobra.Command{Use: "verda"} root.PersistentFlags().String("output", "table", "Output format") root.AddCommand(&cobra.Command{Use: "locations", Short: "List locations", Run: func(*cobra.Command, []string) {}}) - files, err := Generate(root, testVersion) - if err != nil { - t.Fatal(err) - } - if page := string(files["reference/locations.md"]); !strings.Contains(page, "verda locations [flags]") { + if page := generate(t, root)["reference/locations.md"]; !strings.Contains(page, "verda locations [flags]") { t.Errorf("usage should include [flags] from global flags, as --help does; got:\n%s", page) } } @@ -249,11 +221,7 @@ func registryLsSection(t *testing.T, addFlags func(*pflag.FlagSet)) string { registry.AddCommand(ls) root.AddCommand(registry) - files, err := Generate(root, testVersion) - if err != nil { - t.Fatal(err) - } - page := string(files["reference/registry.md"]) + page := generate(t, root)["reference/registry.md"] _, section, ok := strings.Cut(page, "## verda registry ls\n") if !ok { t.Fatalf("page has no registry ls section; got:\n%s", page) From 1648d4d00e6694e5e3733baa8bd14ba06c9038ca Mon Sep 17 00:00:00 2001 From: Dmitrii Iutkin Date: Tue, 10 Nov 2026 10:52:31 +0200 Subject: [PATCH 6/6] docs: generate the command reference for v1.10.0 Output of `make docs VERSION=v1.10.0` with this branch's generator run on the v1.10.0 sources (generator files copied onto `git archive v1.10.0`). The pages describe the installed v1.10.0, not main. Help-text changes made on main since v1.10.0 appear at the next release. No hand edits. Co-Authored-By: Claude Opus 5.5 --- docs/commands.md | 293 ++++++--------- docs/reference/auth.md | 120 ++++++ docs/reference/availability.md | 49 +++ docs/reference/completion.md | 62 ++++ docs/reference/container.md | 286 +++++++++++++++ docs/reference/cost.md | 107 ++++++ docs/reference/doctor.md | 32 ++ docs/reference/images.md | 45 +++ docs/reference/instance-types.md | 53 +++ docs/reference/locations.md | 28 ++ docs/reference/mcp.md | 44 +++ docs/reference/object-storage.md | 609 +++++++++++++++++++++++++++++++ docs/reference/registry.md | 464 +++++++++++++++++++++++ docs/reference/settings.md | 42 +++ docs/reference/skills.md | 177 +++++++++ docs/reference/ssh-key.md | 109 ++++++ docs/reference/ssh.md | 58 +++ docs/reference/startup-script.md | 113 ++++++ docs/reference/status.md | 30 ++ docs/reference/template.md | 192 ++++++++++ docs/reference/update.md | 53 +++ docs/reference/version.md | 17 + docs/reference/vm.md | 416 +++++++++++++++++++++ docs/reference/volume.md | 201 ++++++++++ 24 files changed, 3426 insertions(+), 174 deletions(-) create mode 100644 docs/reference/auth.md create mode 100644 docs/reference/availability.md create mode 100644 docs/reference/completion.md create mode 100644 docs/reference/container.md create mode 100644 docs/reference/cost.md create mode 100644 docs/reference/doctor.md create mode 100644 docs/reference/images.md create mode 100644 docs/reference/instance-types.md create mode 100644 docs/reference/locations.md create mode 100644 docs/reference/mcp.md create mode 100644 docs/reference/object-storage.md create mode 100644 docs/reference/registry.md create mode 100644 docs/reference/settings.md create mode 100644 docs/reference/skills.md create mode 100644 docs/reference/ssh-key.md create mode 100644 docs/reference/ssh.md create mode 100644 docs/reference/startup-script.md create mode 100644 docs/reference/status.md create mode 100644 docs/reference/template.md create mode 100644 docs/reference/update.md create mode 100644 docs/reference/version.md create mode 100644 docs/reference/vm.md create mode 100644 docs/reference/volume.md diff --git a/docs/commands.md b/docs/commands.md index ccda1909..2565fb5d 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -1,203 +1,148 @@ -# Command Reference - -Full reference for all Verda CLI commands and flags. - -## VM - -| Command | Description | -|---------|-------------| -| `verda vm create` | Create a VM (interactive wizard or flags) | -| `verda vm list` | List and inspect VM instances | -| `verda vm describe` | Show detailed info about a single VM | -| `verda vm action` | Start, shutdown, hibernate (deprecated), or delete a VM | -| `verda vm availability` | Show available instance types with pricing | + -Hibernate is deprecated and will be removed in a future version. It discontinues compute and retains volumes. Retained volumes continue billing. +# Command Reference -## SSH +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) -```bash -# Connect by hostname -verda ssh gpu-runner +Every Verda CLI command, grouped as in `verda --help`. Each entry links to its reference page with +usage, flags and examples. The pages are generated from the CLI's own help text. -# Connect with options -verda ssh gpu-runner --user ubuntu --key ~/.ssh/id_ed25519 +See also: [Authentication](guides/authentication.md) · [Scripting and agent mode](guides/scripting.md) · +[Agent error format](agent-errors.md) · [AI skills](ai-skills.md) -# Port forwarding and other ssh args -verda ssh gpu-runner -- -L 8080:localhost:8080 -``` - -## Volume +## Auth Commands | Command | Description | |---------|-------------| -| `verda volume create` | Create a block storage volume | -| `verda volume list` | List volumes | -| `verda volume describe` | Show detailed info about a single volume | -| `verda volume action` | Detach, rename, resize, clone, or delete | -| `verda volume trash` | List deleted volumes (restorable within 96h) | - -## Instance Types, Images, Locations & Availability - -```bash -# Browse instance types with specs and pricing -verda instance-types -verda instance-types --gpu # GPU only -verda instance-types --cpu # CPU only -verda instance-types --spot # spot pricing - -# List all OS images -verda images -verda images --type 1V100.6V # compatible with instance type -verda images --category ubuntu # filter by category - -# List datacenter locations -verda locations - -# Check capacity -verda availability # full matrix -verda availability --location FIN-01 # specific location -verda availability --type 1V100.6V # specific type -verda availability --spot # spot only -``` +| [`verda auth`](reference/auth.md) | Manage shared credentials and profiles | +| [`verda auth login`](reference/auth.md#verda-auth-login) | Save API credentials for a profile | +| [`verda auth show`](reference/auth.md#verda-auth-show) | Show the resolved auth profile | +| [`verda auth use`](reference/auth.md#verda-auth-use) | Switch the active auth profile | -## Cost & Billing - -```bash -# Estimate costs before creating -verda cost estimate --type 1V100.6V --os-volume 100 --storage 500 -verda cost estimate --type 1V100.6V --spot - -# See what your running instances are costing you -verda cost running - -# Account balance -verda cost balance -``` - -## SSH Keys & Startup Scripts +## VM Commands | Command | Description | |---------|-------------| -| `verda ssh-key list / add / delete` | Manage SSH keys | -| `verda startup-script list / add / delete` | Manage startup scripts | - -## Auth +| [`verda vm`](reference/vm.md) | Manage virtual machines | +| [`verda vm action`](reference/vm.md#verda-vm-action) | Perform actions on a VM instance | +| [`verda vm availability`](reference/vm.md#verda-vm-availability) | Show available instance types with specs and pricing | +| [`verda vm create`](reference/vm.md#verda-vm-create) | Create a VM instance | +| [`verda vm delete`](reference/vm.md#verda-vm-delete) | Delete a VM instance | +| [`verda vm describe`](reference/vm.md#verda-vm-describe) | Show detailed information about a VM instance | +| [`verda vm hibernate`](reference/vm.md#verda-vm-hibernate) | Hibernate a VM instance (deprecated, will be removed in a future version) | +| [`verda vm list`](reference/vm.md#verda-vm-list) | List VM instances | +| [`verda vm shutdown`](reference/vm.md#verda-vm-shutdown) | Shutdown a VM instance | +| [`verda vm start`](reference/vm.md#verda-vm-start) | Start a VM instance | +| [`verda ssh`](reference/ssh.md) | SSH into a running VM instance | + +## Serverless Commands | Command | Description | |---------|-------------| -| `verda auth login` | Save API credentials (interactive wizard) | -| `verda auth show` | Show active profile and credentials path | -| `verda auth use PROFILE` | Switch active auth profile | - -### Credential Resolution Order - -Flags, environment variables, `~/.verda/config.yaml` and the credentials file -are checked in a fixed order for each credential, the credentials file path and -the profile. `verda auth --help` lists that order. - -### Environment Variables - -Pairs such as `VERDA_AUTH_CLIENT_ID` and `VERDA_CLIENT_ID` set the same value at -different precedence. - -| Variable | Description | -|----------|-------------| -| `VERDA_CLIENT_ID` | API client ID | -| `VERDA_CLIENT_SECRET` | API client secret | -| `VERDA_AUTH_CLIENT_ID` | API client ID | -| `VERDA_AUTH_CLIENT_SECRET` | API client secret | -| `VERDA_AUTH_TOKEN` | Bearer token | -| `VERDA_PROFILE` | Credentials profile name | -| `VERDA_AUTH_PROFILE` | Credentials profile name | -| `VERDA_AUTH_CREDENTIALS_FILE` | Path to credentials file | -| `VERDA_SHARED_CREDENTIALS_FILE` | Path to credentials file | -| `VERDA_AGENT` | Enable agent mode (`1` or `true`) | -| `VERDA_HOME` | Base directory for config (default `~/.verda`) | - -```bash -# Use env vars for CI/CD pipelines -export VERDA_CLIENT_ID=your-client-id -export VERDA_CLIENT_SECRET=your-client-secret -verda vm list -``` - -## Settings +| [`verda container`](reference/container.md) (beta) | Manage serverless container deployments (always-on endpoints) | +| [`verda container create`](reference/container.md#verda-container-create) | Create a serverless container deployment | +| [`verda container delete`](reference/container.md#verda-container-delete) | Delete a container deployment | +| [`verda container describe`](reference/container.md#verda-container-describe) | Show details of a container deployment | +| [`verda container list`](reference/container.md#verda-container-list) | List serverless container deployments | +| [`verda container pause`](reference/container.md#verda-container-pause) | Pause a container deployment | +| [`verda container purge-queue`](reference/container.md#verda-container-purge-queue) | Purge the pending-request queue for a container deployment | +| [`verda container replicas`](reference/container.md#verda-container-replicas) | List the replicas of a container deployment | +| [`verda container restart`](reference/container.md#verda-container-restart) | Restart a container deployment | +| [`verda container resume`](reference/container.md#verda-container-resume) | Resume a paused container deployment | +| [`verda container scale`](reference/container.md#verda-container-scale) | Change the scaling options of a container deployment | + +## Resource Commands | Command | Description | |---------|-------------| -| `verda settings theme` | Interactive theme picker | -| `verda settings theme ` | Set the color theme directly | - -`verda settings theme --help` lists the available themes. - -## Update +| [`verda availability`](reference/availability.md) | Check instance type availability | +| [`verda images`](reference/images.md) | List available OS images | +| [`verda instance-types`](reference/instance-types.md) | List the instance type catalog with specs and pricing | +| [`verda locations`](reference/locations.md) | List available datacenter locations | +| [`verda registry`](reference/registry.md) (beta) | Manage the Verda Cloud Container Registry (vccr.io) | +| [`verda registry configure`](reference/registry.md#verda-registry-configure) | Configure Verda Container Registry credentials | +| [`verda registry configure-docker`](reference/registry.md#verda-registry-configure-docker) | Set up Docker/compose/helm to pull from VCR (writes ~/.docker/config.json) | +| [`verda registry copy`](reference/registry.md#verda-registry-copy) | Copy an image between registries | +| [`verda registry delete`](reference/registry.md#verda-registry-delete) | Delete a repository or a single image | +| [`verda registry ls`](reference/registry.md#verda-registry-ls) | List repositories in the active Verda project | +| [`verda registry push`](reference/registry.md#verda-registry-push) | Push local images to the container registry | +| [`verda registry show`](reference/registry.md#verda-registry-show) | Show Verda Container Registry credential status | +| [`verda registry tags`](reference/registry.md#verda-registry-tags) | List tags in a container repository | +| [`verda object-storage`](reference/object-storage.md) (beta) | Manage S3 object storage | +| [`verda object-storage abort-uploads`](reference/object-storage.md#verda-object-storage-abort-uploads) | Abort in-progress multipart uploads to reclaim storage | +| [`verda object-storage configure`](reference/object-storage.md#verda-object-storage-configure) | Configure S3 object storage credentials | +| [`verda object-storage cp`](reference/object-storage.md#verda-object-storage-cp) | Copy files between local and S3, or between S3 buckets | +| [`verda object-storage ls`](reference/object-storage.md#verda-object-storage-ls) | List buckets or objects in an S3 bucket | +| [`verda object-storage ls-uploads`](reference/object-storage.md#verda-object-storage-ls-uploads) | List in-progress (incomplete) multipart uploads | +| [`verda object-storage mb`](reference/object-storage.md#verda-object-storage-mb) | Create (make) an S3 bucket | +| [`verda object-storage mv`](reference/object-storage.md#verda-object-storage-mv) | Move files between local and S3, or between S3 buckets | +| [`verda object-storage presign`](reference/object-storage.md#verda-object-storage-presign) | Generate a presigned GET URL for an S3 object | +| [`verda object-storage rb`](reference/object-storage.md#verda-object-storage-rb) | Remove (delete) an S3 bucket | +| [`verda object-storage rm`](reference/object-storage.md#verda-object-storage-rm) | Delete objects from an S3 bucket | +| [`verda object-storage show`](reference/object-storage.md#verda-object-storage-show) | Show S3 credential status | +| [`verda object-storage sync`](reference/object-storage.md#verda-object-storage-sync) | Incrementally sync a directory/prefix with S3 | +| [`verda ssh-key`](reference/ssh-key.md) | Manage SSH keys | +| [`verda ssh-key add`](reference/ssh-key.md#verda-ssh-key-add) | Add an SSH key | +| [`verda ssh-key delete`](reference/ssh-key.md#verda-ssh-key-delete) | Delete an SSH key | +| [`verda ssh-key list`](reference/ssh-key.md#verda-ssh-key-list) | List SSH keys | +| [`verda startup-script`](reference/startup-script.md) | Manage startup scripts | +| [`verda startup-script add`](reference/startup-script.md#verda-startup-script-add) | Add a startup script | +| [`verda startup-script delete`](reference/startup-script.md#verda-startup-script-delete) | Delete a startup script | +| [`verda startup-script list`](reference/startup-script.md#verda-startup-script-list) | List startup scripts | +| [`verda template`](reference/template.md) | Manage reusable resource templates | +| [`verda template create`](reference/template.md#verda-template-create) | Create a new resource template interactively | +| [`verda template delete`](reference/template.md#verda-template-delete) | Delete a saved template | +| [`verda template edit`](reference/template.md#verda-template-edit) | Edit fields of an existing template | +| [`verda template list`](reference/template.md#verda-template-list) | List saved templates | +| [`verda template show`](reference/template.md#verda-template-show) | Show details of a saved template | +| [`verda volume`](reference/volume.md) | Manage volumes | +| [`verda volume action`](reference/volume.md#verda-volume-action) | Perform actions on a volume | +| [`verda volume create`](reference/volume.md#verda-volume-create) | Create a new volume | +| [`verda volume delete`](reference/volume.md#verda-volume-delete) | Delete volumes | +| [`verda volume describe`](reference/volume.md#verda-volume-describe) | Show detailed information about a volume | +| [`verda volume list`](reference/volume.md#verda-volume-list) | List volumes | +| [`verda volume trash`](reference/volume.md#verda-volume-trash) | List volumes in trash | + +## Info Commands | Command | Description | |---------|-------------| -| `verda update` | Update to the latest version | -| `verda update --target v1.0.0` | Install a specific version (upgrade or downgrade) | -| `verda update --list` | List available versions | -| `verda update --verify` | Verify the binary checksum against the GitHub release | +| [`verda status`](reference/status.md) | Show dashboard overview of your Verda Cloud resources | +| [`verda cost`](reference/cost.md) | Cost estimates, pricing, and account balance | +| [`verda cost balance`](reference/cost.md#verda-cost-balance) | Show account balance | +| [`verda cost estimate`](reference/cost.md#verda-cost-estimate) | Estimate costs for an instance configuration | +| [`verda cost running`](reference/cost.md#verda-cost-running) | Estimate the ongoing cost of running instances | -## Shell Completion +## AI Agent Commands -```bash -# Bash -source <(verda completion bash) +| Command | Description | +|---------|-------------| +| [`verda mcp`](reference/mcp.md) | MCP server for AI agent integration (beta) | +| [`verda mcp serve`](reference/mcp.md#verda-mcp-serve) | Start MCP server on stdio | +| [`verda skills`](reference/skills.md) | Manage AI agent skills for Verda Cloud | +| [`verda skills install`](reference/skills.md#verda-skills-install) | Install AI agent skills for Verda Cloud | +| [`verda skills status`](reference/skills.md#verda-skills-status) | Show installed skills status | +| [`verda skills uninstall`](reference/skills.md#verda-skills-uninstall) | Remove installed AI agent skills | -# Zsh (add to ~/.zshrc or run once) -verda completion zsh > "${fpath[1]}/_verda" +## Other Commands -# Fish -verda completion fish | source -``` +| Command | Description | +|---------|-------------| +| [`verda completion`](reference/completion.md) | Generate shell completion scripts | +| [`verda doctor`](reference/doctor.md) | Diagnose common issues | +| [`verda settings`](reference/settings.md) | Manage CLI settings | +| [`verda settings theme`](reference/settings.md#verda-settings-theme) | View or change the CLI color theme | +| [`verda update`](reference/update.md) | Update Verda CLI to the latest or a specific version | +| [`verda version`](reference/version.md) | Print version information | ## Global Flags -| Flag | Description | -|------|-------------| -| `--version, -v` | Print version information | -| `--output, -o` | Output format: `table`, `json`, `yaml` (default: table) | -| `--agent` | Agent mode: JSON output, no prompts, structured errors | -| `--debug` | Enable debug output (API request/response details) | -| `--timeout` | HTTP request timeout (default: 30s) | -| `--base-url` | Override API base URL | -| `--config` | Path to config file (default: `~/.verda/config.yaml`) | - -## Structured Output - -All list and describe commands support `--output json` and `--output yaml` for scripting: - -```bash -# Pipe to jq -verda vm list -o json | jq '.[].hostname' - -# YAML output -verda volume describe vol-123 -o yaml - -# Use in CI/CD scripts -INSTANCE_ID=$(verda vm list -o json | jq -r '.[0].id') +```text + --agent Agent mode: JSON output, no interactive prompts, structured errors + --base-url string API base URL (default "https://api.verda.com/v1") + --config string Path to a verda config file (YAML) + --debug Enable debug output + -o, --output string Output format: table, json, yaml (default "table") + --timeout duration Default HTTP request timeout (default 30s) + -v, --version Print version information ``` - -## Wait for Operations - -Async commands support `--wait` to poll until completion: - -```bash -verda vm create --hostname gpu-runner --wait --wait-timeout 10m -verda vm action --id abc-123 --wait -verda volume create --name data --size 500 --wait -``` - -## Agent Mode (Beta) - -The `--agent` flag optimizes CLI behavior for AI agents and scripts: - -```bash -verda --agent vm list # JSON output, no interactive picker -verda --agent vm create ... # structured errors for missing flags -verda --agent vm action --id X --action shutdown --yes # no confirmation prompt -``` - -See [Agent Errors](agent-errors.md) for the structured error format. diff --git a/docs/reference/auth.md b/docs/reference/auth.md new file mode 100644 index 00000000..0186b4be --- /dev/null +++ b/docs/reference/auth.md @@ -0,0 +1,120 @@ + + +# verda auth + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Manage shared credentials and profiles + +Manage Verda shared credentials and the active auth profile. + +Configuration is resolved from multiple sources in order of precedence: + +```text +1. Command-line flags (highest priority) +2. Environment variables with VERDA_ prefix +3. Credentials file: ~/.verda/credentials or --credentials-file path +4. Built-in defaults +``` + +Subcommands: + +- [`verda auth login`](#verda-auth-login): Save API credentials for a profile +- [`verda auth show`](#verda-auth-show): Show the resolved auth profile +- [`verda auth use`](#verda-auth-use): Switch the active auth profile + +## verda auth login + +Save API credentials for a profile + +Save credentials to a shared credentials file in AWS-style INI format. + +Default file: ~/.verda/credentials +Override with --credentials-file or VERDA_SHARED_CREDENTIALS_FILE. + +Credentials are stored per profile: + +```text +[default] +verda_base_url = https://api.verda.com/v1 +verda_client_id = your-client-id +verda_client_secret = your-client-secret +``` + +**Usage** + +```text +verda auth login [flags] +``` + +**Flags** + +```text + --base-url string Verda API base URL (default "https://api.verda.com/v1") + --client-id string Verda API client ID + --client-secret string Verda API client secret + --credentials-file string Path to the shared credentials file + --profile string Credentials profile name (default "default") +``` + +**Examples** + +```bash +# Interactive wizard (prompts for all fields) +verda auth login + +# Non-interactive with flags +verda auth login \ +--client-id your-client-id \ +--client-secret your-client-secret + +# Staging profile with custom API endpoint +verda auth login \ +--profile staging \ +--base-url https://staging-api.verda.com/v1 \ +--client-id staging-id \ +--client-secret staging-secret + +# Custom credentials file +verda auth login \ +--credentials-file /path/to/credentials \ +--client-id your-id \ +--client-secret your-secret +``` + +## verda auth show + +Show the resolved auth profile + +Show the active auth profile and shared credentials file path. + +**Usage** + +```text +verda auth show [flags] +``` + +## verda auth use + +Switch the active auth profile + +Set the default auth profile in ~/.verda/config.yaml. + +If no profile name is given, an interactive list of available +profiles is shown. + +**Usage** + +```text +verda auth use [PROFILE] [flags] +``` + +**Flags** + +```text + --credentials-file string Path to the shared credentials file +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/availability.md b/docs/reference/availability.md new file mode 100644 index 00000000..94f27b9f --- /dev/null +++ b/docs/reference/availability.md @@ -0,0 +1,49 @@ + + +# verda availability + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Check instance type availability + +Check which instance types are available in each location. +Optionally filter by location, instance type, or spot pricing. + +**Usage** + +```text +verda availability [flags] +``` + +Aliases: `avail` + +**Flags** + +```text + --location string Filter by location code (e.g., FIN-01) + --spot Check spot instance availability + --type string Check availability for a specific instance type +``` + +**Examples** + +```bash +# Full availability matrix +verda availability + +# Check a specific location +verda availability --location FIN-01 + +# Check a specific instance type +verda availability --type 1V100.6V + +# Spot availability only +verda availability --spot + +# JSON output +verda availability -o json +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/completion.md b/docs/reference/completion.md new file mode 100644 index 00000000..99c07bca --- /dev/null +++ b/docs/reference/completion.md @@ -0,0 +1,62 @@ + + +# verda completion + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Generate shell completion scripts + +Generate shell completion scripts for verda. + +Bash: + +```text +source <(verda completion bash) + +# To load completions for each session, execute once: +# Linux: +verda completion bash > /etc/bash_completion.d/verda +# macOS: +verda completion bash > $(brew --prefix)/etc/bash_completion.d/verda +``` + +Zsh: + +```text +# If shell completion is not already enabled in your environment, +# you will need to enable it. You can execute the following once: +echo "autoload -U compinit; compinit" >> ~/.zshrc + +# To load completions for each session, execute once: +verda completion zsh > "${fpath[1]}/_verda" + +# You will need to start a new shell for this setup to take effect. +``` + +Fish: + +```text +verda completion fish | source + +# To load completions for each session, execute once: +verda completion fish > ~/.config/fish/completions/verda.fish +``` + +PowerShell: + +```text +verda completion powershell | Out-String | Invoke-Expression + +# To load completions for every new session, add the output to your profile: +verda completion powershell >> $PROFILE +``` + +**Usage** + +```text +verda completion [bash|zsh|fish|powershell] +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/container.md b/docs/reference/container.md new file mode 100644 index 00000000..9e81067e --- /dev/null +++ b/docs/reference/container.md @@ -0,0 +1,286 @@ + + +# verda container (beta) + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Manage serverless container deployments (always-on endpoints) + +Create and manage always-on serverless container deployments. Each +deployment exposes an HTTPS endpoint that auto-scales based on queue +load, CPU/GPU utilization, or manual replica limits. + +Subcommands: + +- [`verda container create`](#verda-container-create): Create a serverless container deployment +- [`verda container delete`](#verda-container-delete): Delete a container deployment +- [`verda container describe`](#verda-container-describe): Show details of a container deployment +- [`verda container list`](#verda-container-list): List serverless container deployments +- [`verda container pause`](#verda-container-pause): Pause a container deployment +- [`verda container purge-queue`](#verda-container-purge-queue): Purge the pending-request queue for a container deployment +- [`verda container replicas`](#verda-container-replicas): List the replicas of a container deployment +- [`verda container restart`](#verda-container-restart): Restart a container deployment +- [`verda container resume`](#verda-container-resume): Resume a paused container deployment +- [`verda container scale`](#verda-container-scale): Change the scaling options of a container deployment + +## verda container create + +Create a serverless container deployment + +Create an always-on serverless container deployment. If --name, +--image or --compute is missing (outside agent mode), an interactive +wizard asks for the settings. With flags, builds the deployment +request directly and submits it. + +Images must use a specific tag — ":latest" is rejected client-side. + +**Usage** + +```text +verda container create [flags] +``` + +**Flags** + +```text + --cmd stringArray Override image CMD; repeat for multiple args + --compute string Compute resource name (e.g. RTX4500Ada, CPUNode) + --compute-size int Number of GPUs or vCPU cores per replica (default 1) + --concurrency int Concurrent requests per replica (default 1) + --cpu-util int CPU utilization trigger threshold % (5..100); 0 = off + --entrypoint stringArray Override image ENTRYPOINT; repeat for multiple args + --env stringArray Environment variable KEY=VALUE (KEY uppercase); repeat for multiple + --env-secret stringArray Secret-backed env KEY=SECRET_NAME (KEY uppercase); repeat for multiple + --gpu-util int GPU utilization trigger threshold % (5..100); 0 = off + --healthcheck-off Disable healthcheck (default: on at /health) + --healthcheck-path string Healthcheck HTTP path (default "/health") + --healthcheck-port int Healthcheck HTTP port (defaults to --port) + --image string Container image reference (must not be ':latest') + --max-replicas int Maximum replica count (default 3) + --min-replicas int Minimum replica count (0 = scale-to-zero) + --name string Deployment name (URL slug; immutable after create) + --port int Exposed HTTP port (default 80) + --queue-load int Custom queue-load threshold (1..1000); sets --queue-preset=custom when used + --queue-preset string Scaling preset: instant | balanced | cost-saver | custom (default "balanced") + --registry-creds string Registry credentials name (empty = public) + --request-ttl duration How long a pending request may live before deletion (default 5m0s) + --scale-down-delay duration Delay before scaling down (default 5m0s) + --scale-up-delay duration Delay before scaling up + --secret-mount stringArray Secret mount SECRET:MOUNT_PATH; repeat for multiple + --spot Use spot compute instead of on-demand + -y, --yes Skip confirmation (required in agent mode) +``` + +**Examples** + +```bash +# Minimal flag-driven +verda container create \ +--name my-endpoint \ +--image ghcr.io/ai-dock/comfyui:cpu-22.04 \ +--compute RTX4500Ada --compute-size 1 + +# With env vars and scaling preset +verda container create \ +--name my-api --image ghcr.io/me/llm:v1.2 \ +--compute RTX4500Ada --compute-size 1 \ +--env HF_HOME=/data/.huggingface \ +--max-replicas 5 --queue-preset cost-saver +``` + +## verda container delete + +Delete a container deployment + +**Usage** + +```text +verda container delete [flags] +``` + +Aliases: `rm`, `del` + +**Flags** + +```text + --timeout-ms int Server-side wait timeout in ms (0 to skip wait; negative uses API default) (default -1) + -y, --yes Skip confirmation (required in agent mode) +``` + +## verda container describe + +Show details of a container deployment + +**Usage** + +```text +verda container describe [flags] +``` + +Aliases: `get`, `show` + +## verda container list + +List serverless container deployments + +List container deployments. On a terminal, you can type to filter, +select a deployment to view details, and return to the list. + +**Usage** + +```text +verda container list [flags] +``` + +Aliases: `ls` + +**Flags** + +```text + --status string Filter by exact status, case-insensitive (e.g., healthy, unhealthy, paused) +``` + +**Examples** + +```bash +verda container list +verda container ls +verda container list --status healthy +``` + +## verda container pause + +Pause a container deployment + +**Usage** + +```text +verda container pause [flags] +``` + +## verda container purge-queue + +Purge the pending-request queue for a container deployment + +**Usage** + +```text +verda container purge-queue [flags] +``` + +**Flags** + +```text + -y, --yes Skip confirmation (required in agent mode) +``` + +## verda container replicas + +List the replicas of a container deployment + +List the current replicas of a container deployment with their status +and start time, and a count per status (running, initializing, +imagepulling, terminating, error, unavailable). Use it after +'verda container scale' to watch replicas start or stop. + +**Usage** + +```text +verda container replicas [] [flags] +``` + +**Examples** + +```bash +verda container replicas my-api +verda container replicas my-api -o json +``` + +## verda container restart + +Restart a container deployment + +**Usage** + +```text +verda container restart [flags] +``` + +**Flags** + +```text + -y, --yes Skip confirmation (required in agent mode) +``` + +## verda container resume + +Resume a paused container deployment + +**Usage** + +```text +verda container resume [flags] +``` + +## verda container scale + +Change the scaling options of a container deployment + +Change the scaling options of a container deployment. Only the options +you set change; everything else keeps its current value. + +Raising --min-replicas keeps that many replicas running and billed even +with no traffic. --max-replicas caps the billed replicas under load. + +Without option flags on a terminal, an interactive flow shows the current +options and asks which to change. Every change is confirmed; --yes skips +the confirmation and is required in agent mode and without a terminal. + +The API accepts the change at once, but reads show it only after about +5-20 seconds. --wait polls until the new options are visible. Replicas +then start or stop on their own; watch them with +'verda container replicas'. + +**Usage** + +```text +verda container scale [] [flags] +``` + +**Flags** + +```text + --concurrency int Concurrent requests per replica (1..5000) + --cpu-util string CPU utilization trigger: threshold % (5..100) to turn it on, or off + --gpu-util string GPU utilization trigger: threshold % (5..100) to turn it on, or off; not on CPU compute + --max-replicas int Maximum replicas (1..1000) + --min-replicas int Minimum replicas (0..1000; 0 = scale to zero when idle) + --queue-load float Queue-load threshold (1..1000, fractions allowed); implies --queue-preset custom + --queue-preset string Queue-load preset: instant | balanced | cost-saver | custom + --request-ttl duration How long a queued request may wait before it is dropped (0s..24h, whole seconds) + --scale-down-delay duration Delay before scaling down (0s..1h, whole seconds) + --scale-up-delay duration Delay before scaling up (0s..1h, whole seconds) + --wait Wait until reads show the new options (not until replicas are ready) + --wait-timeout duration Maximum time to wait with --wait (default 1m0s) + -y, --yes Skip confirmation (required in agent mode and without a terminal) +``` + +**Examples** + +```bash +# Interactive: pick a deployment and the options to change +verda container scale + +# Keep one replica warm and allow up to five +verda container scale my-api --min-replicas 1 --max-replicas 5 + +# Scale to zero when idle, and wait until reads show the change +verda container scale my-api --min-replicas 0 --yes --wait + +# Turn on the CPU trigger at 70%, turn off the GPU trigger +verda container scale my-api --cpu-util 70 --gpu-util off +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/cost.md b/docs/reference/cost.md new file mode 100644 index 00000000..288b69b7 --- /dev/null +++ b/docs/reference/cost.md @@ -0,0 +1,107 @@ + + +# verda cost + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Cost estimates, pricing, and account balance + +Estimate costs, view pricing, and check account balance. + +Figures here are estimates built from catalog prices, for planning. +The web console is the authority on what you are charged: it +accounts for credits, discounts and contract terms this CLI cannot +see. Where the two differ, the web console is right. + +Subcommands: + +- [`verda cost balance`](#verda-cost-balance): Show account balance +- [`verda cost estimate`](#verda-cost-estimate): Estimate costs for an instance configuration +- [`verda cost running`](#verda-cost-running): Estimate the ongoing cost of running instances + +## verda cost balance + +Show account balance + +Display the current account balance and currency. + +**Usage** + +```text +verda cost balance [flags] +``` + +**Examples** + +```bash +verda cost balance +verda cost balance -o json +``` + +## verda cost estimate + +Estimate costs for an instance configuration + +Calculate estimated costs for an instance type with optional +OS volume and additional storage. Shows hourly, daily, and +monthly breakdowns. + +**Usage** + +```text +verda cost estimate [flags] +``` + +**Flags** + +```text + --os-volume int OS volume size in GiB + --spot Use spot pricing + --storage int Additional storage size in GiB + --storage-type string Storage type: NVMe or HDD (default "NVMe") + --type string Instance type (required) +``` + +**Examples** + +```bash +# Basic estimate +verda cost estimate --type 1V100.6V + +# With storage +verda cost estimate --type 1V100.6V --os-volume 100 --storage 500 + +# Spot pricing +verda cost estimate --type 1V100.6V --spot + +# JSON output +verda cost estimate --type 1V100.6V --storage 500 -o json +``` + +## verda cost running + +Estimate the ongoing cost of running instances + +Estimate what currently running instances and their attached volumes +cost per hour, day and month, with a per-instance breakdown. + +This is a sum of catalog prices, not an invoice: it excludes credits, +discounts, contract terms and partial-hour handling. Check the web console +for actual charges. + +**Usage** + +```text +verda cost running [flags] +``` + +**Examples** + +```bash +verda cost running +verda cost running -o json +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/doctor.md b/docs/reference/doctor.md new file mode 100644 index 00000000..c4521458 --- /dev/null +++ b/docs/reference/doctor.md @@ -0,0 +1,32 @@ + + +# verda doctor + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Diagnose common issues + +Run a series of diagnostic checks against your Verda CLI +installation and report any issues found. Checks include +credential configuration, API reachability, authentication, +CLI version, binary location, and directory permissions. + +**Usage** + +```text +verda doctor [flags] +``` + +**Examples** + +```bash +# Run all diagnostic checks +verda doctor + +# Output as JSON for scripting +verda doctor -o json +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/images.md b/docs/reference/images.md new file mode 100644 index 00000000..69060835 --- /dev/null +++ b/docs/reference/images.md @@ -0,0 +1,45 @@ + + +# verda images + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +List available OS images + +List available OS images. Optionally filter by instance type +to show only compatible images, or by category. + +**Usage** + +```text +verda images [flags] +``` + +Aliases: `image`, `img` + +**Flags** + +```text + --category string Filter by category (e.g., ubuntu, pytorch) + --type string Filter images compatible with this instance type +``` + +**Examples** + +```bash +# List all images +verda images + +# Images compatible with a specific instance type +verda images --type 1V100.6V + +# Filter by category +verda images --category ubuntu + +# JSON output for scripting +verda images -o json +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/instance-types.md b/docs/reference/instance-types.md new file mode 100644 index 00000000..6d60608f --- /dev/null +++ b/docs/reference/instance-types.md @@ -0,0 +1,53 @@ + + +# verda instance-types + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +List the instance type catalog with specs and pricing + +List every instance type Verda offers, with specifications and pricing. +Filter by GPU or CPU to narrow results. + +This is the catalog, not live stock: a type listed here may have no +capacity in any location right now. Run "verda availability" for what +is actually deployable, per location. + +**Usage** + +```text +verda instance-types [flags] +``` + +Aliases: `types` + +**Flags** + +```text + --cpu Show only CPU instance types + --gpu Show only GPU instance types + --spot Show spot pricing instead of on-demand +``` + +**Examples** + +```bash +# All instance types +verda instance-types + +# GPU instances only +verda instance-types --gpu + +# CPU instances only +verda instance-types --cpu + +# Show spot pricing +verda instance-types --spot + +# JSON output +verda instance-types -o json +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/locations.md b/docs/reference/locations.md new file mode 100644 index 00000000..ebcfacc5 --- /dev/null +++ b/docs/reference/locations.md @@ -0,0 +1,28 @@ + + +# verda locations + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +List available datacenter locations + +List all available Verda Cloud datacenter locations. + +**Usage** + +```text +verda locations [flags] +``` + +Aliases: `location`, `loc` + +**Examples** + +```bash +verda locations +verda locations -o json +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/mcp.md b/docs/reference/mcp.md new file mode 100644 index 00000000..a24e4fc3 --- /dev/null +++ b/docs/reference/mcp.md @@ -0,0 +1,44 @@ + + +# verda mcp + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +MCP server for AI agent integration (beta) + +[Beta] Model Context Protocol (MCP) server that exposes Verda Cloud +operations as structured tools for AI agents. + +Requires valid credentials — run "verda auth login" first. + +Subcommands: + +- [`verda mcp serve`](#verda-mcp-serve): Start MCP server on stdio + +## verda mcp serve + +Start MCP server on stdio + +Start a Model Context Protocol (MCP) server that communicates +over stdin/stdout. Configure in your AI agent: + +```text +{ + "mcpServers": { + "verda": { + "command": "verda", + "args": ["mcp", "serve"] + } + } +} +``` + +**Usage** + +```text +verda mcp serve [flags] +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/object-storage.md b/docs/reference/object-storage.md new file mode 100644 index 00000000..13427343 --- /dev/null +++ b/docs/reference/object-storage.md @@ -0,0 +1,609 @@ + + +# verda object-storage (beta) + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Manage S3 object storage + +Manage S3-compatible object storage credentials and operations. + +S3 credentials are stored separately from API credentials in the +same credentials file (~/.verda/credentials) using verda_s3_ prefixed keys. + +Configure credentials: + +```text +verda object-storage configure +``` + +Show current S3 credential status: + +```text +verda object-storage show +``` + +Aliases: `oss`, `d4` + +Subcommands: + +- [`verda object-storage abort-uploads`](#verda-object-storage-abort-uploads): Abort in-progress multipart uploads to reclaim storage +- [`verda object-storage configure`](#verda-object-storage-configure): Configure S3 object storage credentials +- [`verda object-storage cp`](#verda-object-storage-cp): Copy files between local and S3, or between S3 buckets +- [`verda object-storage ls`](#verda-object-storage-ls): List buckets or objects in an S3 bucket +- [`verda object-storage ls-uploads`](#verda-object-storage-ls-uploads): List in-progress (incomplete) multipart uploads +- [`verda object-storage mb`](#verda-object-storage-mb): Create (make) an S3 bucket +- [`verda object-storage mv`](#verda-object-storage-mv): Move files between local and S3, or between S3 buckets +- [`verda object-storage presign`](#verda-object-storage-presign): Generate a presigned GET URL for an S3 object +- [`verda object-storage rb`](#verda-object-storage-rb): Remove (delete) an S3 bucket +- [`verda object-storage rm`](#verda-object-storage-rm): Delete objects from an S3 bucket +- [`verda object-storage show`](#verda-object-storage-show): Show S3 credential status +- [`verda object-storage sync`](#verda-object-storage-sync): Incrementally sync a directory/prefix with S3 + +## verda object-storage abort-uploads + +Abort in-progress multipart uploads to reclaim storage + +Abort in-progress (incomplete) multipart uploads in a bucket. The +staged parts of an incomplete upload consume real, billed storage +even though the object never appears in "verda object-storage ls". Aborting +reclaims that storage. + +Use --older-than to abort only uploads initiated before a given age +(e.g. 7d, 12h), and --key to target a single object key. Without +either, EVERY in-progress upload in the bucket is aborted. + +This is destructive: aborted uploads cannot be resumed and their +parts are deleted. In --agent mode, --yes is required. + +**Usage** + +```text +verda object-storage abort-uploads s3://bucket [flags] +``` + +**Flags** + +```text + --key string Only abort uploads for this exact object key + --older-than string Only abort uploads initiated before this age (e.g. 7d, 12h) + --prefix string Only abort uploads whose key starts with this prefix + --yes Skip confirmation prompt +``` + +**Examples** + +```bash +# Abort uploads older than 7 days +verda object-storage abort-uploads s3://my-bucket --older-than 7d + +# Abort every in-progress upload (with confirmation) +verda object-storage abort-uploads s3://my-bucket + +# Abort uploads for a single key +verda object-storage abort-uploads s3://my-bucket --key path/to/big.bin + +# Skip the confirmation prompt +verda object-storage abort-uploads s3://my-bucket --older-than 30d --yes +``` + +## verda object-storage configure + +Configure S3 object storage credentials + +Save S3 object storage credentials to the shared credentials file. + +Create an access key first in the Verda dashboard: log in, select your +project, then open Project management → Credentials → Object Storage +Access Keys. The endpoint and region are pre-filled with sensible +defaults, so you usually only need to paste the access key and secret. + +S3 credentials are stored alongside API credentials using verda_s3_ +prefixed keys. Profile switching (--profile) works across both. + +Default file: ~/.verda/credentials +Override with --credentials-file or VERDA_SHARED_CREDENTIALS_FILE. + +Resolution order for every object-storage command, per field: + +```text +1. Command flags (--access-key, --secret-key, --endpoint, --region) +2. VERDA_S3_ACCESS_KEY, VERDA_S3_SECRET_KEY, VERDA_S3_ENDPOINT, + VERDA_S3_REGION, VERDA_S3_AUTH_MODE +3. The credentials-file profile above +``` + +The merge is per field, not all-or-nothing: setting only +VERDA_S3_ENDPOINT overrides the endpoint and keeps the profile's keys. +An empty variable counts as unset. A complete env set needs no file at +all, which is how CI avoids writing secrets to disk. + +**Usage** + +```text +verda object-storage configure [flags] +``` + +**Flags** + +```text + --access-key string S3 access key ID + --credentials-file string Path to the shared credentials file + --endpoint string S3 endpoint URL + --profile string Credentials profile name (default "default") + --region string S3 region (default "eu-north-3") + --secret-key string S3 secret access key +``` + +**Examples** + +```bash +# Interactive wizard (prompts for all fields) +verda object-storage configure + +# Non-interactive with flags +verda object-storage configure \ +--access-key AKIA1234567890EXAMPLE \ +--secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLE \ +--endpoint https://objects.lab.verda.storage + +# Different profile +verda object-storage configure \ +--profile staging \ +--access-key AKIA... \ +--secret-key ... \ +--endpoint https://staging.objects.verda.storage +``` + +## verda object-storage cp + +Copy files between local and S3, or between S3 buckets + +Copy files between local paths and S3 URIs, or between two S3 +URIs. At least one of <src> or <dst> must be an s3:// URI. + +With --recursive, uploads walk the local directory, and S3 +downloads / copies paginate through every object under the +source prefix. --include and --exclude glob patterns filter +the set (matched against the relative path; '\*' does not +cross '/'). + +Large single-file uploads and single-object downloads are multipart + +```text +and parallel, and they RESUME: re-run the EXACT same command to +continue an interrupted transfer (only the missing parts move). +--no-resume starts over; --concurrency / --part-size tune throughput. +Interactive downloads from the "verda object-storage ls" browser resume the same way. + +With --dryrun, the planned transfers are listed but no SDK +``` + +calls are made. + +**Usage** + +```text +verda object-storage cp [flags] +``` + +**Flags** + +```text + --concurrency int Parallel parts for large uploads/downloads (default 5) + --content-type string Override Content-Type on uploads + --dryrun Preview transfers without performing them + --exclude stringArray Skip entries matching this glob (repeatable, overrides --include) + --include stringArray Only copy entries matching this glob (repeatable) + --no-resume Ignore saved progress and restart the transfer (upload or download) + --part-size string Part size for large uploads/downloads, e.g. 32MiB (default auto) + --recursive Copy every file under a directory/prefix +``` + +**Examples** + +```bash +# Upload a single file +verda object-storage cp ./report.csv s3://my-bucket/reports/report.csv + +# Upload into a "folder" (trailing slash keeps the filename) +verda object-storage cp ./report.csv s3://my-bucket/reports/ + +# Download a single object +verda object-storage cp s3://my-bucket/report.csv ./report.csv + +# Download into a directory (keeps the object's name) +verda object-storage cp s3://my-bucket/report.csv ./downloads/ + +# Recursively download a whole prefix +verda object-storage cp s3://my-bucket/logs/ ./logs --recursive + +# Resume an interrupted upload or download — re-run the same command +verda object-storage cp ./model.bin s3://my-bucket/model.bin +verda object-storage cp s3://my-bucket/model.bin ./model.bin + +# Faster large transfer +verda object-storage cp s3://my-bucket/model.bin ./model.bin --concurrency 16 --part-size 32MiB + +# Copy between buckets +verda object-storage cp s3://src/a.txt s3://dst/b.txt + +# Recursive upload with filter +verda object-storage cp ./data s3://my-bucket/data/ --recursive --include "*.csv" + +# Recursive upload, skipping temp files +verda object-storage cp ./site s3://my-bucket/site/ --recursive --exclude "*.tmp" + +# Override the content type on upload +verda object-storage cp ./page.html s3://my-bucket/page.html --content-type text/html + +# Preview a recursive download +verda object-storage cp s3://my-bucket/logs/ ./logs --recursive --dryrun +``` + +## verda object-storage ls + +List buckets or objects in an S3 bucket + +List buckets when invoked with no arguments, or list the +top-level keys + common prefixes under an s3:// URI. + +Pass --recursive to flatten all keys under the prefix. + +**Usage** + +```text +verda object-storage ls [s3://bucket[/prefix/]] [flags] +``` + +**Flags** + +```text + --human-readable Display sizes in human-friendly units (KB, MB, ...) + --recursive List all keys under the prefix (no delimiter) + --summarize Append a total objects/size footer +``` + +**Examples** + +```bash +# List all buckets +verda object-storage ls + +# List top-level keys under a bucket +verda object-storage ls s3://my-bucket + +# List keys under a prefix +verda object-storage ls s3://my-bucket/prefix/ + +# Recursively list every key in the bucket +verda object-storage ls s3://my-bucket --recursive + +# Human-readable sizes + summary +verda object-storage ls s3://my-bucket --human-readable --summarize +``` + +## verda object-storage ls-uploads + +List in-progress (incomplete) multipart uploads + +List in-progress multipart uploads in a bucket. The staged parts of +an incomplete upload consume real storage and are billed even though +the object does not appear in "verda object-storage ls". This command surfaces +that hidden cost: key, UploadId, when it was initiated, and the +accumulated size of the parts uploaded so far. + +Use "verda object-storage abort-uploads" to reclaim the storage. + +**Usage** + +```text +verda object-storage ls-uploads s3://bucket [flags] +``` + +**Flags** + +```text + --prefix string Only list uploads whose key starts with this prefix +``` + +**Examples** + +```bash +# List every in-progress upload in a bucket +verda object-storage ls-uploads s3://my-bucket + +# Only uploads under a key prefix +verda object-storage ls-uploads s3://my-bucket --prefix logs/ + +# Machine-readable output +verda object-storage ls-uploads s3://my-bucket -o json +``` + +## verda object-storage mb + +Create (make) an S3 bucket + +Create a new S3 bucket. The URI must be a bucket-only URI +(s3://bucket) with no key component. + +Run with no argument on a terminal to be prompted for the name. + +**Usage** + +```text +verda object-storage mb s3://bucket [flags] +``` + +**Examples** + +```bash +# Create a new bucket +verda object-storage mb s3://my-new-bucket + +# Prompt for the name interactively +verda object-storage mb +``` + +## verda object-storage mv + +Move files between local and S3, or between S3 buckets + +Move files between local paths and S3 URIs, or between two S3 +URIs. At least one of <src> or <dst> must be an s3:// URI. A +move is a copy followed by a delete of the source — the source +is only removed once the transfer succeeds. + +With --recursive, local moves walk the directory and S3 moves +paginate through every object under the source prefix. +--include and --exclude glob patterns filter the set (matched +against the relative path; '\*' does not cross '/'). + +With --dryrun, the planned moves are listed but no SDK calls +or local filesystem changes are made. + +**Usage** + +```text +verda object-storage mv [flags] +``` + +**Flags** + +```text + --content-type string Override Content-Type on uploads + --dryrun Preview moves without performing them + --exclude stringArray Skip entries matching this glob (repeatable, overrides --include) + --include stringArray Only move entries matching this glob (repeatable) + --recursive Move every file under a directory/prefix +``` + +**Examples** + +```bash +# Move a single file to S3 (removes the local source on success) +verda object-storage mv ./report.csv s3://my-bucket/reports/report.csv + +# Move an object out of S3 to local disk +verda object-storage mv s3://my-bucket/report.csv ./report.csv + +# Move between buckets +verda object-storage mv s3://src/a.txt s3://dst/b.txt + +# Recursive move of every .csv file under a directory +verda object-storage mv ./data s3://my-bucket/data/ --recursive --include "*.csv" + +# Preview a recursive move +verda object-storage mv s3://my-bucket/logs/ ./logs --recursive --dryrun + +# Move/rename an object interactively (S3 -> S3) +verda object-storage mv +``` + +## verda object-storage presign + +Generate a presigned GET URL for an S3 object + +Generate a time-limited HTTPS URL that grants GET access to an +object without exposing your S3 credentials. The URL expires after +the duration given by --expires-in (default 1h). + +**Usage** + +```text +verda object-storage presign s3://bucket/key [flags] +``` + +**Flags** + +```text + --expires-in duration URL expiration (e.g. 15m, 1h, 24h) (default 1h0m0s) +``` + +**Examples** + +```bash +verda object-storage presign s3://my-bucket/report.csv +verda object-storage presign s3://my-bucket/report.csv --expires-in 15m +verda object-storage presign s3://my-bucket/report.csv --expires-in 24h +``` + +## verda object-storage rb + +Remove (delete) an S3 bucket + +Remove an S3 bucket. The bucket must be empty unless --force is +passed, in which case all objects are deleted first in batches. + +This action is destructive and cannot be undone. In --agent mode, +--yes is required to proceed. + +**Usage** + +```text +verda object-storage rb s3://bucket [flags] +``` + +**Flags** + +```text + --force Empty the bucket before deletion + --yes Skip confirmation prompt +``` + +**Examples** + +```bash +# Remove an empty bucket +verda object-storage rb s3://my-bucket + +# Remove a non-empty bucket (deletes all objects first) +verda object-storage rb s3://my-bucket --force + +# Skip confirmation prompt +verda object-storage rb s3://my-bucket --yes +``` + +## verda object-storage rm + +Delete objects from an S3 bucket + +Delete one or more objects from an S3 bucket. + +Without --recursive the URI must specify a single object key; +with --recursive the URI is treated as a prefix and every +matching object under it is deleted. --include and --exclude +glob patterns filter the recursive set (matched against the +full key; '\*' does not cross '/'). Excludes take precedence +over includes. + +Pass --dryrun to preview the set of keys without issuing any +deletes. In --agent mode, --yes is required unless --dryrun +is also passed. + +**Usage** + +```text +verda object-storage rm s3://bucket/key [flags] +``` + +**Flags** + +```text + --dryrun Preview deletions without performing them + --exclude stringArray Skip keys matching this glob (repeatable, overrides --include) + --include stringArray Only delete keys matching this glob (repeatable) + --recursive Treat the URI as a prefix and delete all matching objects + --yes Skip confirmation prompt +``` + +**Examples** + +```bash +# Delete a single object +verda object-storage rm s3://my-bucket/path/to/obj.txt + +# Recursively delete every object under a prefix +verda object-storage rm s3://my-bucket/logs/ --recursive + +# Only delete .txt files, keep everything else +verda object-storage rm s3://my-bucket/data/ --recursive --include "*.txt" + +# Delete everything except .log files +verda object-storage rm s3://my-bucket/data/ --recursive --exclude "*.log" + +# Preview without deleting +verda object-storage rm s3://my-bucket/data/ --recursive --dryrun + +# Skip confirmation +verda object-storage rm s3://my-bucket/obj --yes + +# Browse and tick files to delete interactively +verda object-storage rm +``` + +## verda object-storage show + +Show S3 credential status + +Show the current S3 credentials status for a profile. +Secret values are not displayed — only whether they are loaded. + +**Usage** + +```text +verda object-storage show [flags] +``` + +**Flags** + +```text + --credentials-file string Path to the shared credentials file + --profile string Credentials profile to show (default: active profile) +``` + +**Examples** + +```bash +# Show default profile +verda object-storage show + +# Show specific profile +verda object-storage show --profile staging +``` + +## verda object-storage sync + +Incrementally sync a directory/prefix with S3 + +Recursively sync files between a local directory and an S3 +prefix, between two S3 prefixes, or in either direction. Only +new or updated files are copied; unchanged files are skipped. + +By default a file is considered "updated" when the source is +newer OR the sizes differ. Pass --exact-timestamps to require +the timestamps match exactly (any difference triggers a copy). + +With --delete, files present at the destination but not at the +source are removed after the copy phase. Include/exclude glob +filters are applied to the relative path on BOTH sides — an +excluded key is neither copied nor deleted. + +With --dryrun, the planned copies/deletes are listed but no SDK +calls or local filesystem changes are made. + +**Usage** + +```text +verda object-storage sync [flags] +``` + +**Flags** + +```text + --delete Delete destination files that have no corresponding source + --dryrun Preview planned copies/deletes without performing them + --exact-timestamps Require exact timestamp match instead of src-newer + --exclude stringArray Skip entries matching this glob (repeatable, overrides --include) + --include stringArray Only sync entries matching this glob (repeatable) +``` + +**Examples** + +```bash +# Mirror a local directory to S3 +verda object-storage sync ./site s3://my-bucket/site/ + +# Pull a prefix down incrementally +verda object-storage sync s3://my-bucket/backups/ ./backups + +# Copy between buckets, mirroring deletions +verda object-storage sync s3://src/data/ s3://dst/data/ --delete + +# Only sync .csv files, preview first +verda object-storage sync ./data s3://my-bucket/data/ --include "*.csv" --dryrun +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/registry.md b/docs/reference/registry.md new file mode 100644 index 00000000..a4705365 --- /dev/null +++ b/docs/reference/registry.md @@ -0,0 +1,464 @@ + + +# verda registry (beta) + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Manage the Verda Cloud Container Registry (vccr.io) + +Manage Verda Container Registry (vccr.io) credentials, browse +repositories, push local Docker images, and copy images between +registries. + +Credentials are stored separately from API credentials in +~/.verda/credentials using verda_registry_ prefixed keys. + +Aliases: `vccr`, `vcr` + +Subcommands: + +- [`verda registry configure`](#verda-registry-configure): Configure Verda Container Registry credentials +- [`verda registry configure-docker`](#verda-registry-configure-docker): Set up Docker/compose/helm to pull from VCR (writes ~/.docker/config.json) +- [`verda registry copy`](#verda-registry-copy): Copy an image between registries +- [`verda registry delete`](#verda-registry-delete): Delete a repository or a single image +- [`verda registry ls`](#verda-registry-ls): List repositories in the active Verda project +- [`verda registry push`](#verda-registry-push): Push local images to the container registry +- [`verda registry show`](#verda-registry-show): Show Verda Container Registry credential status +- [`verda registry tags`](#verda-registry-tags): List tags in a container repository + +## verda registry configure + +Configure Verda Container Registry credentials + +Save Verda Container Registry credentials to ~/.verda/credentials +(override with --credentials-file or VERDA_REGISTRY_CREDENTIALS_FILE). +Stored with verda_registry_ prefixed keys alongside API and S3 keys; +other keys in the profile are preserved. + +Three ways to provide credentials: + +```text +• interactive — run with no flags on a terminal; the wizard guides you, + including where to find the credential in the web UI. +• --paste — paste the web UI's "Registry authentication command" (the + docker login … line); the host is auto-detected. +• --username + --password-stdin [--endpoint] — Docker-style; --endpoint + defaults to the profile's saved host, else vccr.io. +``` + +Find the credential in the web UI under: select project → Credentials → +Create credentials. + +**Usage** + +```text +verda registry configure [flags] +``` + +**Flags** + +```text + --credentials-file string Path to the shared credentials file + --docker-config verda registry configure-docker Also write ~/.docker/config.json (same merge as verda registry configure-docker) + --endpoint string Registry host (e.g. "vccr.io"). Defaults to the saved endpoint for this profile, or "vccr.io" on production. + --expires-in int Days from now until the credentials expire (default 30) + --password-stdin Read the registry secret from stdin + --paste docker login ... Full docker login ... command to parse (alternative to --username/--password-stdin) + --profile string Credentials profile name (default: active profile) + --username string Registry username (vcr-+) +``` + +**Examples** + +```bash +# Interactive wizard (recommended for first-time setup) +verda registry configure + +# Paste the web UI's "Registry authentication command" +verda registry configure --paste "docker login -u vcr-abc+cli -p s3cret vccr.io" + +# Username + secret on stdin (--endpoint defaults to vccr.io) +echo -n "$SECRET" | verda registry configure --username vcr-abc+cli --password-stdin +``` + +## verda registry configure-docker + +Set up Docker/compose/helm to pull from VCR (writes ~/.docker/config.json) + +Write the active Verda Container Registry credentials into the Docker +config file so third-party tools (docker pull, docker-compose, +helm pull oci://, nerdctl) can authenticate against the registry. + +This command does NOT talk to the registry; it is a local file merge. +Existing entries for other registries, as well as unknown top-level +keys (credsStore, credHelpers, HttpHeaders, ...), are preserved +verbatim. + +Default Docker config path: ~/.docker/config.json +Override with --config or DOCKER_CONFIG. + +**Usage** + +```text +verda registry configure-docker [flags] +``` + +Aliases: `login` + +**Flags** + +```text + --config string Path to the Docker config file (default ~/.docker/config.json) + --credentials-file string Path to the shared Verda credentials file + --profile string Credentials profile to read (default: active profile) +``` + +**Examples** + +```bash +# Write the default profile into ~/.docker/config.json +verda registry configure-docker + +# Use a specific profile +verda registry configure-docker --profile staging + +# Write to a non-default Docker config file +verda registry configure-docker --config /tmp/docker/config.json +``` + +## verda registry copy + +Copy an image between registries + +Copy a single image from a source registry to the configured +Verda Container Registry. + +The source must be a fully qualified reference (e.g. +"docker.io/library/nginx:1.25"). The destination, if omitted, +defaults to the active registry endpoint + project with the +source repository and tag preserved. A short destination +(e.g. "my-app:prod") is expanded via the active credentials +to "<endpoint>/<project>/my-app:prod". + +Source-side credentials are resolved via ~/.docker/config.json +and registered credential helpers by default. Pass +--src-auth anonymous to skip the keychain entirely or +--src-auth basic plus --src-username / --src-password-stdin +to supply explicit credentials. Run with no arguments on a terminal to launch an interactive wizard that prompts for the source, access mode, scope (this tag / all tags), and destination, then runs the copy. + +**Usage** + +```text +verda registry copy [] [flags] +``` + +Aliases: `cp` + +**Flags** + +```text + --all-tags Copy every tag in the source repository + --credentials-file string Path to credentials file + --dry-run Resolve and summarize what would be copied; no writes. Ignores --overwrite. + --image-jobs int Image-level parallelism for --all-tags (0 = auto) + --jobs int Layer-level parallelism (0 = ggcr default) + --overwrite Allow replacing an existing destination tag (ignored under --dry-run) + --profile string Credentials profile name (default: active profile) + --progress string Progress output: auto|plain|json|none (default "auto") + --retries int Maximum attempts for idempotent HTTP operations on transient errors (default 5) + --src-auth string Source authentication mode: docker-config|anonymous|basic (default "docker-config") + --src-password-stdin Read the source registry password from stdin (required with --src-auth basic) + --src-username string Source registry username (required with --src-auth basic) + --yes Skip the overwrite confirmation prompt; implies --overwrite +``` + +**Examples** + +```bash +# Copy a public image from Docker Hub to VCR under the same repo/tag +verda registry copy docker.io/library/nginx:1.25 + +# Copy to a custom destination +verda registry copy gcr.io/my-project/app:v1 my-app:prod + +# Use basic auth on the source side +echo "$SRC_PASSWORD" | verda registry copy \ +private.example.com/app:v1 \ +--src-auth basic --src-username jdoe --src-password-stdin + +# JSON output for scripts +verda registry copy docker.io/library/nginx:1.25 -o json +``` + +## verda registry delete + +Delete a repository or a single image + +Delete a repository or a single image (artifact) from the active +Verda project. + +A bare repository argument removes the repository and every +artifact / tag under it (equivalent to Harbor's "Delete image +repository" button). Appending :TAG or @DIGEST scopes the +delete to a single artifact — the same semantics as the web +UI's per-row "Delete image": the manifest and every tag that +pointed at it are removed in one call. + +Without an argument on a terminal, delete enters an interactive +flow: pick a repository, then choose between deleting selected +images or the whole repository. Piping or redirecting stdout +disables the interactive flow — scripts must always pass an +explicit target. Agent mode (--agent) requires --yes for every +destructive operation, matching the safety contract used by +`verda vm delete`. + +**Usage** + +```text +verda registry delete [REPOSITORY[:TAG|@DIGEST]] [flags] +``` + +Aliases: `del`, `rm` + +**Flags** + +```text + --credentials-file string Path to the shared Verda credentials file + --profile string Credentials profile to read (default: active profile) + -y, --yes Skip confirmation (required in agent mode) +``` + +**Examples** + +```bash +# Interactive: pick a repo, then delete images or the whole repo +verda registry delete + +# Delete a whole repository (all artifacts, all tags) +verda registry delete library/hello-world + +# Delete a single artifact by tag +verda registry delete library/hello-world:latest + +# Delete a single artifact by digest +verda registry delete library/hello-world@sha256:d1a8d0a4eeb6 + +# Skip confirmation (required in agent mode) +verda registry delete library/hello-world --yes +``` + +## verda registry ls + +List repositories in the active Verda project + +List every repository in the Verda project associated with the +active registry credentials. Repositories are resolved via +Harbor's REST API, not the Docker Registry v2 catalog endpoint — +the catalog endpoint is admin-only on Harbor and is not +accessible to the project-scoped robot accounts VCR issues. + +When run on a terminal, selecting a repository drills into its +per-artifact details (digest, tags, size, push/pull times). +When piped to a file or another command (or when -o json/yaml +is set), ls prints a single non-interactive document. + +**Usage** + +```text +verda registry ls [flags] +``` + +**Flags** + +```text + --credentials-file string Path to the shared Verda credentials file + --profile string Credentials profile to read (default: active profile) +``` + +**Examples** + +```bash +# Interactive: pick a repo to see its image list +verda registry ls + +# Non-interactive table (piping suppresses the picker) +verda registry ls | less + +# JSON output for scripts +verda registry ls -o json + +# Use a non-default credentials profile +verda registry ls --profile staging +``` + +## verda registry push + +Push local images to the container registry + +Upload one or more local images to Verda Container Registry. + +Each positional argument is a local reference resolved through +the --source pipeline: + +```text +- auto (default) picks oci for directories, tar for .tar/.tar.gz + files, and daemon for everything else after probing the + Docker daemon. +- daemon reads the image from the local Docker daemon. +- oci reads an OCI image layout from a directory. +- tar reads a Docker/OCI tarball from a file. +``` + +The destination repository defaults to the local reference's +repository name under the active credentials' project; use +--repo / --tag to override (single-image only). + +For v1 images are pushed sequentially; parallelism across +images will arrive with the interactive progress view. + +**Usage** + +```text +verda registry push [...] [flags] +``` + +**Flags** + +```text + --credentials-file string Path to credentials file + --image-jobs int Image-level parallelism (v1: always 1) (default 1) + --jobs int Layer-level parallelism (0 = ggcr default) + --no-mount Disable cross-repo blob mount (v1: flag is a no-op) + --profile string Credentials profile name (default: active profile) + --progress string Progress output: auto|plain|json|none (default "auto") + --repo string Override destination repository name (single-image only) + --retries int Maximum attempts for idempotent HTTP operations on transient errors (default 5) + --source string Image source: auto|daemon|oci|tar (default "auto") + --tag string Override destination tag (single-image only) +``` + +**Examples** + +```bash +# Push a single image from the Docker daemon +verda registry push my-app:v1 + +# Push multiple images sequentially +verda registry push my-app:v1 worker:v1 edge:v1 + +# Push with a different destination repo and tag +verda registry push my-app:latest --repo team/api --tag prod + +# Push from an OCI layout directory +verda registry push --source oci ./build/image + +# Push from a tarball +verda registry push --source tar ./out/image.tar + +# JSON output for scripts +verda registry push my-app:v1 -o json +``` + +## verda registry show + +Show Verda Container Registry credential status + +Show the current Verda Container Registry credential status for a +profile. The secret is never displayed — only whether credentials +are loaded, their username, endpoint, project id, and expiry. + +If no credentials are configured for the profile, the command +reports "not configured" and exits 0. + +**Usage** + +```text +verda registry show [flags] +``` + +**Flags** + +```text + --credentials-file string Path to the shared credentials file + --profile string Credentials profile to show (default: active profile) +``` + +**Examples** + +```bash +# Show the default profile +verda registry show + +# Show a specific profile +verda registry show --profile staging + +# JSON output (e.g. for scripting) +verda registry show -o json +``` + +## verda registry tags + +List tags in a container repository + +List every tag in the given repository plus per-tag metadata +(digest, size). On a terminal, tags are shown as an interactive, +filterable picker — select one to print its full pull reference and +exit (the same picker "verda registry ls" uses when you drill into a +repository). Piped output, -o json/yaml, or --agent print the table +instead. + +The repository may be passed as a full reference +("vccr.io/<project>/<name>") or a short reference ("<name>"). Short +references are expanded using the active registry credentials. If +a tag component is included in the argument (e.g. "app:v1"), it is +ignored — tags always operates on the full repository. + +The full tag list is always fetched from the registry. Per-tag +HEAD lookups for digest/size are capped by --limit to keep +response time bounded on repositories with many tags. Tags past +the cap are listed by name with "--" in the DIGEST and SIZE +columns. + +Pass --all to run HEAD lookups for every tag regardless of +--limit. --limit 0 is equivalent to --all. + +The "PUSHED" column is reserved for a future release and currently +prints "--" for every row. + +**Usage** + +```text +verda registry tags [flags] +``` + +**Flags** + +```text + --all Run metadata lookups for every tag (overrides --limit) + --credentials-file string Path to the shared Verda credentials file + --limit int Cap on per-tag metadata lookups (0 = unlimited) (default 50) + --profile string Credentials profile to read (default: active profile) +``` + +**Examples** + +```bash +# List tags in a short-form repository +verda registry tags my-app + +# List tags in a fully qualified repository +verda registry tags vccr.io/my-project/my-app + +# Raise the metadata cap +verda registry tags my-app --limit 200 + +# Metadata for every tag (slower on repositories with many tags) +verda registry tags my-app --all + +# JSON output for scripts +verda registry tags my-app -o json +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/settings.md b/docs/reference/settings.md new file mode 100644 index 00000000..13e22fa6 --- /dev/null +++ b/docs/reference/settings.md @@ -0,0 +1,42 @@ + + +# verda settings + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Manage CLI settings + +View and update CLI settings stored in ~/.verda/config.yaml. + +Subcommands: + +- [`verda settings theme`](#verda-settings-theme): View or change the CLI color theme + +## verda settings theme + +View or change the CLI color theme + +View and change the CLI color theme. + +Without arguments, opens an interactive theme selector. +With a theme name, sets it directly. + +**Usage** + +```text +verda settings theme [name] [flags] +``` + +**Examples** + +```bash +# Interactive selection +verda settings theme + +# Set a theme directly +verda settings theme dracula +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/skills.md b/docs/reference/skills.md new file mode 100644 index 00000000..83ce02e7 --- /dev/null +++ b/docs/reference/skills.md @@ -0,0 +1,177 @@ + + +# verda skills + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Manage AI agent skills for Verda Cloud + +Install, update, and manage AI agent skill files that teach coding +agents how to use the Verda CLI for cloud infrastructure management. + +Skills teach AI agents to: + +```text +- Discover instance types, availability, and pricing +- Deploy GPU/CPU VMs with proper dependency chains +- Manage lifecycle (start, stop, delete) with safety checks +- Handle costs, volumes, SSH keys, and startup scripts +- Use --agent and -o json flags correctly +``` + +Skills are bundled with the CLI binary — no network fetch needed. +They are versioned with the CLI, so updating the CLI updates skills. + +Supported agents: Claude Code, Cursor, Windsurf, Codex, Gemini CLI, Copilot. +Custom agents can be added via ~/.verda/agents.json. + +**Examples** + +```bash +# Install skills for your AI coding agent +verda skills install claude-code + +# Install for multiple agents at once +verda skills install claude-code cursor windsurf + +# Check installed version and available updates +verda skills status + +# Add a custom agent via ~/.verda/agents.json: +# { "agents": { "aider": { "display_name": "Aider", +# "scope": "project", "target": ".aider/instructions.md", +# "method": "append" } } } +verda skills install aider +``` + +Subcommands: + +- [`verda skills install`](#verda-skills-install): Install AI agent skills for Verda Cloud +- [`verda skills status`](#verda-skills-status): Show installed skills status +- [`verda skills uninstall`](#verda-skills-uninstall): Remove installed AI agent skills + +## verda skills install + +Install AI agent skills for Verda Cloud + +Install skill files that teach AI coding agents how to use the +Verda CLI. Skills are bundled with the CLI binary and versioned +with each release. + +Two skill files are installed per agent: + +```text +- verda-cloud.md: Decision engine (deploy workflow, cost checks, error recovery) +- verda-reference.md: Command reference (flags, output fields, parameter sources) +``` + +Install methods vary by agent: + +```text +- copy: Files placed in agent's rules directory (Claude Code, Cursor, Windsurf) +- append: Content injected between markers in a target file (Codex, Gemini, Copilot) +``` + +Without arguments, shows an interactive picker to select agents. +With arguments, installs for the specified agents directly. + +**Usage** + +```text +verda skills install [agents...] [flags] +``` + +**Flags** + +```text + --force Skip confirmation and reinstall even if already installed +``` + +**Examples** + +```bash +# Interactive — select agents from a list +verda skills install + +# Install for Claude Code (writes to ~/.claude/skills/) +verda skills install claude-code + +# Install for multiple agents at once +verda skills install claude-code cursor windsurf + +# Reinstall / update without confirmation +verda skills install claude-code --force + +# Non-interactive for CI/scripts (defaults to claude-code) +verda --agent skills install claude-code +``` + +## verda skills status + +Show installed skills status + +Display the currently installed skills version, which agents +have skills installed, and whether a newer version is bundled +with this CLI build. + +The "latest" version is the one embedded in the current CLI binary. +If your installed version differs, run "verda skills install" to update. + +**Usage** + +```text +verda skills status [flags] +``` + +**Examples** + +```bash +# Human-readable output +verda skills status + +# Structured output for scripts +verda skills status -o json + +# Check if update is available (JSON fields: version, latest, update_available) +verda --agent skills status -o json +``` + +## verda skills uninstall + +Remove installed AI agent skills + +Remove verda-ai-skills from the specified AI agents. + +For copy-method agents (Claude Code, Cursor, Windsurf), skill files +are deleted from the target directory. For append-method agents +(Codex, Gemini, Copilot), the marked content block is removed from +the target file, preserving surrounding content. + +Without arguments, shows an interactive picker of currently +installed agents to select from. + +**Usage** + +```text +verda skills uninstall [agents...] [flags] +``` + +**Examples** + +```bash +# Interactive — select from installed agents +verda skills uninstall + +# Remove from specific agent +verda skills uninstall claude-code + +# Remove from multiple agents +verda skills uninstall claude-code cursor + +# Non-interactive — remove from all installed agents +verda --agent skills uninstall +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/ssh-key.md b/docs/reference/ssh-key.md new file mode 100644 index 00000000..5be875dd --- /dev/null +++ b/docs/reference/ssh-key.md @@ -0,0 +1,109 @@ + + +# verda ssh-key + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Manage SSH keys + +Create, list, and delete SSH keys used for VM authentication. + +Subcommands: + +- [`verda ssh-key add`](#verda-ssh-key-add): Add an SSH key +- [`verda ssh-key delete`](#verda-ssh-key-delete): Delete an SSH key +- [`verda ssh-key list`](#verda-ssh-key-list): List SSH keys + +## verda ssh-key add + +Add an SSH key + +Add a new SSH key to your account. In interactive mode you will be +prompted for the key name and public key. Use --name and --public-key +flags for non-interactive use. + +**Usage** + +```text +verda ssh-key add [flags] +``` + +**Flags** + +```text + --name string SSH key name + --public-key string SSH public key content +``` + +**Examples** + +```bash +# Interactive +verda ssh-key add + +# Non-interactive +verda ssh-key add --name my-key --public-key "ssh-ed25519 AAAA..." +``` + +## verda ssh-key delete + +Delete an SSH key + +Delete an SSH key from your account. In interactive mode you will be +prompted to select a key and confirm deletion. Pass the key id as an +argument or with --id for non-interactive use. Agent mode requires an +id and --yes. + +**Usage** + +```text +verda ssh-key delete [] [flags] +``` + +Aliases: `rm` + +**Flags** + +```text + --id string SSH key ID to delete (alternative to the positional argument) + --yes Skip confirmation for destructive actions (required in agent mode) +``` + +**Examples** + +```bash +# Interactive +verda ssh-key delete + +# Non-interactive +verda ssh-key delete abc-123 +verda ssh-key delete --id abc-123 + +# Agent mode +verda --agent ssh-key delete abc-123 --yes +``` + +## verda ssh-key list + +List SSH keys + +List all SSH keys in your account, showing Name, ID, and Fingerprint. + +**Usage** + +```text +verda ssh-key list [flags] +``` + +Aliases: `ls` + +**Examples** + +```bash +verda ssh-key list +verda ssh-key ls +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/ssh.md b/docs/reference/ssh.md new file mode 100644 index 00000000..7e94a566 --- /dev/null +++ b/docs/reference/ssh.md @@ -0,0 +1,58 @@ + + +# verda ssh + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +SSH into a running VM instance + +Connect to a running VM instance via SSH. + +The instance can be specified by ID or hostname. The command +resolves the instance's IP address from the API and opens an +SSH connection. + +Any arguments after -- are passed directly to the ssh command. + +Supports piping commands via stdin. When stdin is not a terminal, +the input is forwarded to the remote host and pseudo-TTY allocation +is disabled automatically. + +**Usage** + +```text +verda ssh [-- extra-ssh-args...] [flags] +``` + +**Flags** + +```text + -i, --key string Path to SSH identity file + -u, --user string SSH user (default "root") +``` + +**Examples** + +```bash +# SSH by hostname +verda ssh gpu-runner + +# SSH by instance ID +verda ssh abc-123-def + +# SSH with a specific user and key +verda ssh gpu-runner --user ubuntu --key ~/.ssh/id_ed25519 + +# Pass extra ssh arguments +verda ssh gpu-runner -- -L 8080:localhost:8080 + +# Pipe a command to run remotely +echo "nvidia-smi" | verda ssh gpu-runner + +# Pipe a script +cat setup.sh | verda ssh gpu-runner +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/startup-script.md b/docs/reference/startup-script.md new file mode 100644 index 00000000..7e867d4c --- /dev/null +++ b/docs/reference/startup-script.md @@ -0,0 +1,113 @@ + + +# verda startup-script + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Manage startup scripts + +Create, list, and delete startup scripts that run when a VM boots. + +Subcommands: + +- [`verda startup-script add`](#verda-startup-script-add): Add a startup script +- [`verda startup-script delete`](#verda-startup-script-delete): Delete a startup script +- [`verda startup-script list`](#verda-startup-script-list): List startup scripts + +## verda startup-script add + +Add a startup script + +Add a new startup script to your account. In interactive mode you will +be prompted for the script name and then asked to load from a file or +paste the content. Use flags for non-interactive use. + +**Usage** + +```text +verda startup-script add [flags] +``` + +**Flags** + +```text + --file string Path to a script file + --name string Script name + --script string Inline script content +``` + +**Examples** + +```bash +# Interactive +verda startup-script add + +# From file +verda startup-script add --name setup --file ./init.sh + +# Inline script +verda startup-script add --name setup --script "#!/bin/bash\napt update" +``` + +## verda startup-script delete + +Delete a startup script + +Delete a startup script from your account. In interactive mode you +will be prompted to select a script and confirm deletion. Pass the +script id as an argument or with --id for non-interactive use. Agent +mode requires an id and --yes. + +**Usage** + +```text +verda startup-script delete [] [flags] +``` + +Aliases: `rm` + +**Flags** + +```text + --id string Startup script ID to delete (alternative to the positional argument) + --yes Skip confirmation for destructive actions (required in agent mode) +``` + +**Examples** + +```bash +# Interactive +verda startup-script delete + +# Non-interactive +verda startup-script delete abc-123 +verda startup-script delete --id abc-123 + +# Agent mode +verda --agent startup-script delete abc-123 --yes +``` + +## verda startup-script list + +List startup scripts + +List all startup scripts in your account, showing Name, ID, and CreatedAt. + +**Usage** + +```text +verda startup-script list [flags] +``` + +Aliases: `ls` + +**Examples** + +```bash +verda startup-script list +verda script ls +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/status.md b/docs/reference/status.md new file mode 100644 index 00000000..adf1705a --- /dev/null +++ b/docs/reference/status.md @@ -0,0 +1,30 @@ + + +# verda status + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Show dashboard overview of your Verda Cloud resources + +Display a dashboard overview including instance and volume +counts, burn rate, account balance, runway estimate, and +resource distribution across locations. + +**Usage** + +```text +verda status [flags] +``` + +Aliases: `dash` + +**Examples** + +```bash +verda status +verda status -o json +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/template.md b/docs/reference/template.md new file mode 100644 index 00000000..0ce04786 --- /dev/null +++ b/docs/reference/template.md @@ -0,0 +1,192 @@ + + +# verda template + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Manage reusable resource templates + +Save, list, show, and delete reusable resource configuration templates. +Templates pre-fill the create wizard so you don't repeat the same settings. + +Aliases: `tmpl` + +Subcommands: + +- [`verda template create`](#verda-template-create): Create a new resource template interactively +- [`verda template delete`](#verda-template-delete): Delete a saved template +- [`verda template edit`](#verda-template-edit): Edit fields of an existing template +- [`verda template list`](#verda-template-list): List saved templates +- [`verda template show`](#verda-template-show): Show details of a saved template + +## verda template create + +Create a new resource template interactively + +Create a reusable resource configuration template by running +the interactive wizard. The wizard collects instance type, +image, location, SSH keys, storage, and other settings. + +Templates are saved as YAML files under ~/.verda/templates/<resource>/. +Names are auto-reformatted: "My GPU Setup" becomes "my-gpu-setup". + +After saving, use "verda vm create --from <name>" to create +instances with pre-filled settings. + +You can manually edit the template YAML to add features like: + +```text +hostname_pattern: "gpu-{random}-{location}" +storage_skip: true +startup_script_skip: true +``` + +**Usage** + +```text +verda template create [name] [flags] +``` + +**Examples** + +```bash +# Create a template interactively +verda template create + +# Create with a name (skips name prompt) +verda template create gpu-training + +# Then use it to create VMs +verda vm create --from gpu-training +verda vm create --from gpu-training --hostname my-vm +``` + +## verda template delete + +Delete a saved template + +Delete a saved resource configuration template. +Without arguments, shows an interactive picker with confirmation. +The argument must be in resource/name format (e.g. vm/gpu-training). +Agent mode requires the template argument and --yes. + +**Usage** + +```text +verda template delete [resource/name] [flags] +``` + +Aliases: `rm` + +**Flags** + +```text + --yes Skip confirmation for destructive actions (required in agent mode) +``` + +**Examples** + +```bash +# Interactive picker +verda template delete + +# Delete a VM template +verda template delete vm/gpu-training + +# Short alias +verda tmpl rm vm/gpu-training + +# Agent mode +verda --agent template delete vm/gpu-training --yes +``` + +## verda template edit + +Edit fields of an existing template + +Edit specific fields of an existing template. Shows a menu of +all template fields with their current values — pick which ones +to change. + +Without arguments, shows an interactive template picker first. + +**Usage** + +```text +verda template edit [resource/name] [flags] +``` + +**Examples** + +```bash +# Interactive picker, then field menu +verda template edit + +# Edit a specific template +verda template edit vm/gpu-training +``` + +## verda template list + +List saved templates + +List all saved resource configuration templates. +Use --type to filter by resource type (e.g. "vm"). + +**Usage** + +```text +verda template list [flags] +``` + +Aliases: `ls` + +**Flags** + +```text + --type string Filter by resource type (e.g. vm) +``` + +**Examples** + +```bash +# List all templates +verda template list + +# List only VM templates +verda template list --type vm + +# Short alias +verda tmpl ls +``` + +## verda template show + +Show details of a saved template + +Display the full configuration of a saved template. +Without arguments, shows an interactive picker. +The argument must be in resource/name format (e.g. vm/gpu-training). + +**Usage** + +```text +verda template show [resource/name] [flags] +``` + +**Examples** + +```bash +# Interactive picker +verda template show + +# Show a VM template +verda template show vm/gpu-training + +# Output as JSON +verda template show vm/gpu-training -o json +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/update.md b/docs/reference/update.md new file mode 100644 index 00000000..d323d0c0 --- /dev/null +++ b/docs/reference/update.md @@ -0,0 +1,53 @@ + + +# verda update + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Update Verda CLI to the latest or a specific version + +Update the Verda CLI binary in-place by downloading from GitHub Releases. +No Go installation required. + +The binary is installed to ~/.verda/bin/ (no sudo required). + +The downloaded archive is verified against the release's SHA256SUMS +before the running binary is replaced; on any verification failure +the update aborts and the binary is left untouched. Use --skip-verify +only as a deliberate escape hatch. + +Without flags, updates to the latest version. +Use --target to install a specific version (upgrade or downgrade). +Use --list to show available versions. + +**Usage** + +```text +verda update [flags] +``` + +**Flags** + +```text + --list List available versions + --skip-verify Skip checksum verification of the downloaded release archive (NOT recommended) + --target string Version to install (e.g. v1.0.0) + --verify Verify the binary checksum against the GitHub release +``` + +**Examples** + +```bash +# Update to latest +verda update + +# Install specific version +verda update --target v1.0.0 + +# List available versions +verda update --list +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/version.md b/docs/reference/version.md new file mode 100644 index 00000000..54cce381 --- /dev/null +++ b/docs/reference/version.md @@ -0,0 +1,17 @@ + + +# verda version + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Print version information + +**Usage** + +```text +verda version [flags] +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/vm.md b/docs/reference/vm.md new file mode 100644 index 00000000..45bf557f --- /dev/null +++ b/docs/reference/vm.md @@ -0,0 +1,416 @@ + + +# verda vm + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Manage virtual machines + +Create and manage Verda virtual machine instances. + +Aliases: `instance`, `instances` + +Subcommands: + +- [`verda vm action`](#verda-vm-action): Perform actions on a VM instance +- [`verda vm availability`](#verda-vm-availability): Show available instance types with specs and pricing +- [`verda vm create`](#verda-vm-create): Create a VM instance +- [`verda vm delete`](#verda-vm-delete): Delete a VM instance +- [`verda vm describe`](#verda-vm-describe): Show detailed information about a VM instance +- [`verda vm hibernate`](#verda-vm-hibernate): Hibernate a VM instance (deprecated, will be removed in a future version) +- [`verda vm list`](#verda-vm-list): List VM instances +- [`verda vm shutdown`](#verda-vm-shutdown): Shutdown a VM instance +- [`verda vm start`](#verda-vm-start): Start a VM instance + +## verda vm action + +Perform actions on a VM instance + +Select a VM instance and perform an action: start, shutdown, +force shutdown, hibernate (deprecated), or delete. + +Hibernate is deprecated and will be removed in a future version. +It discontinues compute and retains volumes. Retained volumes continue billing. + +**Usage** + +```text +verda vm action [flags] +``` + +**Flags** + +```text + --action string Action to perform: start, shutdown, force_shutdown, hibernate (deprecated), delete + --id string Instance ID to act on + --wait Wait for the operation to complete (default true) + --wait-timeout duration Maximum time to wait for the operation (default 5m0s) + --yes Skip confirmation for destructive actions (required in agent mode) +``` + +**Examples** + +```bash +# Interactive: select instance then action +verda vm action + +# Specify instance ID +verda vm action --id abc-123 + +# Run action and wait for completion +verda vm action --id abc-123 --wait + +# Non-interactive (agent mode) +verda --agent vm action --id abc-123 --action shutdown +verda --agent vm action --id abc-123 --action delete --yes +``` + +## verda vm availability + +Show available instance types with specs and pricing + +Show currently available instance types with full specs, pricing, +and datacenter locations. This helps you find what you can launch +right now and how much it costs. + +**Usage** + +```text +verda vm availability [flags] +``` + +Aliases: `avail` + +**Flags** + +```text + --kind string Filter by kind: gpu or cpu + --location string Filter by location code (e.g., FIN-01) + --spot Show spot pricing and availability + --type string Filter by instance type (e.g., 1V100.6V) +``` + +**Examples** + +```bash +# Show all available instance types +verda vm availability + +# Filter by location +verda vm availability --location FIN-01 + +# Check a specific instance type +verda vm availability --type 1V100.6V + +# GPU instances only +verda vm availability --kind gpu + +# Spot pricing +verda vm availability --spot + +# JSON output for scripting +verda vm availability -o json +``` + +## verda vm create + +Create a VM instance + +Create a Verda VM instance. Without flags, launches an interactive +wizard. Use --from to pre-fill settings from a saved template. +Flags passed alongside --from override the template values. + +Templates are created with "verda template create" and stored +as YAML files under ~/.verda/templates/vm/. + +**Usage** + +```text +verda vm create [flags] +``` + +**Flags** + +```text + --contract string Billing contract: pay_as_go, long_term, or spot. Long-term durations are not exposed by POST /v1/instances. + --coupon string Coupon code to apply to the instance creation + --description string Human-readable description; defaults to the hostname + --existing-volume strings Existing volume ID to attach; repeat the flag for multiple volumes + --from string[=" "] Create from a saved template; use alone to pick from list + --hostname string Hostname for the new VM + --instance-type string Instance type, for example 1V100.6V + --is-spot Request a spot instance + --kind string Compute class: gpu or cpu + --location string Location code, for example FIN-01 (default "FIN-01") + --os string OS image slug or an existing detached OS volume ID + --os-volume-name string Name of the OS volume to create; requires --os-volume-size + --os-volume-on-spot-discontinue string Spot discontinue policy for the OS volume: keep_detached, move_to_trash, or delete_permanently; requires --os-volume-size and --is-spot + --os-volume-size int Size of the OS volume in GiB; required if any other --os-volume-* flag is set + --pricing string Pricing mode string accepted by the API, for example FIXED_PRICE + --ssh-key strings SSH key ID to inject into the instance; repeat the flag for multiple keys + --startup-script string Startup script ID to attach + --storage-name string Name of the optional additional storage volume; defaults to -storage + --storage-on-spot-discontinue string Spot discontinue policy for the optional additional storage volume + --storage-size int Size of the optional additional storage volume in GiB + --storage-type string Type of the optional additional storage volume (default "NVMe") + --volume stringArray Create and attach a new volume using name:size:type[:location[:on-spot-discontinue]] + --wait Wait for the operation to complete (default true) + --wait-timeout duration Maximum time to wait for the operation (default 5m0s) +``` + +**Examples** + +```bash +# Interactive wizard +verda vm create + +# From a saved template (only prompts for hostname + confirm) +verda vm create --from gpu-training +verda vm create --from gpu-training --hostname my-vm + +# Pick template from list +verda vm create --from + +# From a template file +verda vm create --from ./my-template.yaml + +# From a template, override specific fields with flags +verda vm create --from gpu-training --location FIN-03 +verda vm create --from gpu-training --hostname my-vm --os-volume-size 200 + +# Non-interactive with all flags +verda vm create \ +--kind gpu \ +--instance-type 1V100.6V \ +--location FIN-01 \ +--os ubuntu-24.04-cuda-13.0-open-docker \ +--os-volume-size 100 \ +--hostname gpu-runner \ +--ssh-key ssh_key_123 +``` + +## verda vm delete + +Delete a VM instance + +**Usage** + +```text +verda vm delete [flags] +``` + +Aliases: `rm` + +**Flags** + +```text + --all Target all instances (use with --status/--hostname to filter) + --hostname string Filter by hostname glob pattern, requires --all (e.g., "test-*") + --id string Instance ID (alternative to positional argument) + --status string Filter by status, requires --all (e.g., running, offline) + --wait Wait for the operation to complete (default true) + --wait-timeout duration Maximum time to wait for the operation (default 5m0s) + --with-volumes Also delete all attached volumes (delete only); without it the OS volume survives detached and keeps billing + --yes Skip confirmation for destructive actions +``` + +**Examples** + +```bash +# Delete a VM instance a specific instance +verda vm delete inst-abc-123 + +# Interactive: select from list +verda vm delete + +# Batch: delete all matching instances +verda vm delete --all --status offline + +# Batch: delete instances matching hostname pattern +verda vm delete --all --hostname "test-*" + +# Batch: combine filters (AND logic) +verda vm delete --all --status offline --hostname "test-*" + +# Batch delete with volumes +verda vm delete --all --status offline --with-volumes --yes +``` + +## verda vm describe + +Show detailed information about a VM instance + +Display detailed information about a single VM instance, +including compute specs, networking, and attached volumes. + +**Usage** + +```text +verda vm describe [flags] +``` + +Aliases: `get`, `show` + +**Examples** + +```bash +verda vm describe abc-123-def +verda vm show abc-123-def +verda vm describe abc-123-def -o json +``` + +## verda vm hibernate + +Hibernate a VM instance (deprecated, will be removed in a future version) + +**Usage** + +```text +verda vm hibernate [flags] +``` + +**Flags** + +```text + --all Target all instances (use with --status/--hostname to filter) + --hostname string Filter by hostname glob pattern, requires --all (e.g., "test-*") + --id string Instance ID (alternative to positional argument) + --status string Filter by status, requires --all (e.g., running, offline) + --wait Wait for the operation to complete (default true) + --wait-timeout duration Maximum time to wait for the operation (default 5m0s) + --yes Skip confirmation for destructive actions +``` + +**Examples** + +```bash +# Hibernate a VM instance (deprecated, will be removed in a future version) a specific instance +verda vm hibernate inst-abc-123 + +# Interactive: select from list +verda vm hibernate + +# Batch: hibernate all matching instances +verda vm hibernate --all --status running + +# Batch: hibernate instances matching hostname pattern +verda vm hibernate --all --hostname "test-*" + +# Batch: combine filters (AND logic) +verda vm hibernate --all --status running --hostname "test-*" +``` + +## verda vm list + +List VM instances + +List all Verda VM instances. Select an instance to view details. + +**Usage** + +```text +verda vm list [flags] +``` + +Aliases: `ls` + +**Flags** + +```text + --location string Filter by location (e.g., FIN-01, FIN-03) + --status string Filter by status (e.g., running, offline, provisioning) +``` + +**Examples** + +```bash +verda vm list +verda vm ls +verda vm list --status running +``` + +## verda vm shutdown + +Shutdown a VM instance + +**Usage** + +```text +verda vm shutdown [flags] +``` + +**Flags** + +```text + --all Target all instances (use with --status/--hostname to filter) + --hostname string Filter by hostname glob pattern, requires --all (e.g., "test-*") + --id string Instance ID (alternative to positional argument) + --status string Filter by status, requires --all (e.g., running, offline) + --wait Wait for the operation to complete (default true) + --wait-timeout duration Maximum time to wait for the operation (default 5m0s) + --yes Skip confirmation for destructive actions +``` + +**Examples** + +```bash +# Shutdown a VM instance a specific instance +verda vm shutdown inst-abc-123 + +# Interactive: select from list +verda vm shutdown + +# Batch: shutdown all matching instances +verda vm shutdown --all --status running + +# Batch: shutdown instances matching hostname pattern +verda vm shutdown --all --hostname "test-*" + +# Batch: combine filters (AND logic) +verda vm shutdown --all --status running --hostname "test-*" +``` + +## verda vm start + +Start a VM instance + +**Usage** + +```text +verda vm start [flags] +``` + +**Flags** + +```text + --all Target all instances (use with --status/--hostname to filter) + --hostname string Filter by hostname glob pattern, requires --all (e.g., "test-*") + --id string Instance ID (alternative to positional argument) + --status string Filter by status, requires --all (e.g., running, offline) + --wait Wait for the operation to complete (default true) + --wait-timeout duration Maximum time to wait for the operation (default 5m0s) + --yes Skip confirmation for destructive actions +``` + +**Examples** + +```bash +# Start a VM instance a specific instance +verda vm start inst-abc-123 + +# Interactive: select from list +verda vm start + +# Batch: start all matching instances +verda vm start --all --status offline + +# Batch: start instances matching hostname pattern +verda vm start --all --hostname "test-*" + +# Batch: combine filters (AND logic) +verda vm start --all --status offline --hostname "test-*" +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags). diff --git a/docs/reference/volume.md b/docs/reference/volume.md new file mode 100644 index 00000000..cfea5d6c --- /dev/null +++ b/docs/reference/volume.md @@ -0,0 +1,201 @@ + + +# verda volume + +> Verda CLI **v1.10.0** · [other versions](https://github.com/verda-cloud/verda-cli/tags) + +Manage volumes + +List and manage Verda block storage volumes. + +Aliases: `vol` + +Subcommands: + +- [`verda volume action`](#verda-volume-action): Perform actions on a volume +- [`verda volume create`](#verda-volume-create): Create a new volume +- [`verda volume delete`](#verda-volume-delete): Delete volumes +- [`verda volume describe`](#verda-volume-describe): Show detailed information about a volume +- [`verda volume list`](#verda-volume-list): List volumes +- [`verda volume trash`](#verda-volume-trash): List volumes in trash + +## verda volume action + +Perform actions on a volume + +Select a volume and perform an action: detach, rename, +resize, clone, or delete. + +**Usage** + +```text +verda volume action [flags] +``` + +**Flags** + +```text + --id string Volume ID to act on + --wait Wait for the operation to complete + --wait-timeout duration Maximum time to wait for the operation (default 5m0s) +``` + +**Examples** + +```bash +verda volume action +verda vol action --id abc-123 +verda vol action --id abc-123 --wait +``` + +## verda volume create + +Create a new volume + +Create a new block storage volume. If flags are omitted, +an interactive prompt guides you through the options. +Agent mode requires all flags and --yes. + +**Usage** + +```text +verda volume create [flags] +``` + +**Flags** + +```text + --location string Location code, e.g. FIN-01 + --name string Volume name + --size int Volume size in GiB + --type string Volume type (default: NVMe) + --wait Wait for the operation to complete + --wait-timeout duration Maximum time to wait for the operation (default 5m0s) + --yes Skip confirmation (required in agent mode) +``` + +**Examples** + +```bash +# Interactive +verda volume create + +# Non-interactive +verda volume create --name my-vol --size 100 --type NVMe --location FIN-01 --yes +``` + +## verda volume delete + +Delete volumes + +Delete one or more volumes. Deleted storage can be restored +within 96 hours via the trash command. + +Without arguments, an interactive multi-select picker is shown. +With a positional argument or --id, a single volume is deleted. +Use --all to target all volumes matching optional --status filter. + +**Usage** + +```text +verda volume delete [volume-id] [flags] +``` + +Aliases: `rm` + +**Flags** + +```text + --all Target all volumes (use with --status to filter) + --id string Volume ID (alternative to positional argument) + --status string Filter by status, requires --all (e.g., detached, attached) + --yes Skip confirmation for destructive actions +``` + +**Examples** + +```bash +# Delete a specific volume +verda volume delete vol-abc-123 + +# Interactive: select from list +verda volume delete + +# Batch: delete all detached volumes +verda volume delete --all --status detached --yes +``` + +## verda volume describe + +Show detailed information about a volume + +Display detailed information about a single volume, +including size, type, status, and attached instance. + +**Usage** + +```text +verda volume describe [flags] +``` + +Aliases: `get`, `show` + +**Examples** + +```bash +verda volume describe abc-123-def +verda vol show abc-123-def +verda volume describe abc-123-def -o json +``` + +## verda volume list + +List volumes + +List all block storage volumes, showing Name, ID, Size, Type, +Status, and Location. Optionally filter by status. + +**Usage** + +```text +verda volume list [flags] +``` + +Aliases: `ls` + +**Flags** + +```text + --status string Filter by volume status (e.g., attached, detached, ordered) +``` + +**Examples** + +```bash +verda volume list +verda vol ls +verda volume list --status attached +``` + +## verda volume trash + +List volumes in trash + +List deleted volumes that can still be restored (within 96 hours). + +**Usage** + +```text +verda volume trash [flags] +``` + +**Examples** + +```bash +verda volume trash +verda vol trash +``` + +--- + +Global flags such as `--output`, `--agent` and `--debug` work with every command: see [Global Flags](../commands.md#global-flags).