Feature/ws cli commands to ws docs

.github/workflows/sync-commands.yaml

@@ -0,0 +1,19 @@
+---
+name: 🔄 Sync commands to ws-meta
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - commands.yaml
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 🔄 Sync to ws-meta
+        uses: kloudkit/ws-meta/.github/actions/sync@main
+        with:
+          token: ${{ secrets.KLOUD_BOT_ORG_PAT }}
+          files: |
+            commands.yaml

cmd/clip/clip.go

@@ -7,4 +7,5 @@ import (
 var ClipCmd = &cobra.Command{
 	Use:   "clip",
 	Short: "Interact with the native clipboard",
+	Long:  "Reach the browser clipboard from the terminal over the workspace IPC socket.",
 }

cmd/clip/paste.go

@@ -8,6 +8,7 @@ import (
 var pasteCmd = &cobra.Command{
 	Use:   "paste",
 	Short: "Paste clipboard content",
+	Long:  "Read the browser clipboard over the workspace IPC socket and write it to stdout — redirect it to a file or pipe it onward. Pairs with the pbcopy/xclip/xsel shims for terminal clipboard access.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return clipboard.Paste(cmd.OutOrStdout())
 	},

cmd/commands_test.go

@@ -0,0 +1,31 @@
+package cmd_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/kloudkit/ws-cli/cmd"
+	"github.com/kloudkit/ws-cli/internals/docs"
+	"gotest.tools/v3/assert"
+)
+
+func TestCommandsManifestMatchesCommittedFile(t *testing.T) {
+	want, err := os.ReadFile(filepath.Join("..", "commands.yaml"))
+	assert.NilError(t, err)
+
+	got, err := docs.Serialize(cmd.RootCmd())
+	assert.NilError(t, err)
+
+	assert.Equal(t, string(got), string(want))
+}
+
+func TestSerializeIsDeterministic(t *testing.T) {
+	first, err := docs.Serialize(cmd.RootCmd())
+	assert.NilError(t, err)
+
+	second, err := docs.Serialize(cmd.RootCmd())
+	assert.NilError(t, err)
+
+	assert.Equal(t, string(first), string(second))
+}

cmd/editor/diagnostics.go

@@ -13,6 +13,7 @@ import (
 var diagnosticsCmd = &cobra.Command{
 	Use:   "diagnostics",
 	Short: "Show language diagnostics for the workspace (or a single file)",
+	Long:  "Pull language-server diagnostics (errors, warnings) from the editor over the IPC socket, across the whole workspace or a single file with --uri. Styled table by default, --raw for the JSON.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		uri, _ := cmd.Flags().GetString("uri")
 

cmd/editor/editor.go

@@ -18,6 +18,7 @@ var errNoEditorOverSSH = errors.New(
 var EditorCmd = &cobra.Command{
 	Use:   "editor",
 	Short: "Inspect and drive the active editor session",
+	Long:  "Query and control the running VS Code / code-server window over the workspace IPC socket — list open tabs, read diagnostics and the current selection, or open a file. Blocked over SSH, where there is no browser editor to reach.",
 	PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
 		if env.IsSSHSession() {
 			return errNoEditorOverSSH

cmd/editor/list.go

@@ -13,6 +13,7 @@ import (
 var listCmd = &cobra.Command{
 	Use:   "list",
 	Short: "List the currently open editor tabs",
+	Long:  "List the editor's open tabs over the IPC socket, with each tab's path, language, and active or dirty state.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		body, err := editoripc.FetchEditors()
 		if err != nil {

cmd/editor/open.go

@@ -12,6 +12,7 @@ import (
 var openCmd = &cobra.Command{
 	Use:   "open <file>",
 	Short: "Open a file in the editor",
+	Long:  "Open a file in the running editor window over the workspace IPC socket — a tab in the current window by default, a separate one with --new-window, jumping to a range with --selection. Fails fast over SSH, where there is no browser editor to open into.",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		newWindow, _ := cmd.Flags().GetBool("new-window")

cmd/editor/selection.go

@@ -13,6 +13,7 @@ import (
 var selectionCmd = &cobra.Command{
 	Use:   "selection",
 	Short: "Show the active editor's current selection",
+	Long:  "Report the active editor's current selection — file, range, and selected text — over the IPC socket. Empty when nothing is selected.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		body, err := editoripc.FetchSelection()
 		if err != nil {

cmd/feature/feature.go

@@ -9,6 +9,7 @@ import (
 var FeatureCmd = &cobra.Command{
 	Use:   "feature",
 	Short: "Install additional pre-configured features",
+	Long:  "Install and inspect optional workspace features — Ansible playbooks that add tools on top of the base image. Ships a curated set; --root points at your own under ~/.ws/features.d.",
 }
 
 func featureDirs(cmd *cobra.Command) []string {

cmd/feature/info.go

@@ -11,6 +11,7 @@ import (
 var infoCmd = &cobra.Command{
 	Use:   "info <name>",
 	Short: "Show detailed information about a feature",
+	Long:  "Show a feature's description and the variables it accepts, so you know what --opt values install will take.",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		featureName := args[0]

cmd/feature/install.go

@@ -25,6 +25,7 @@ var skippableSections = []struct {
 var installCmd = &cobra.Command{
 	Use:   "install",
 	Short: "Install additional pre-configured features",
+	Long:  "Run a feature's playbook to install it. Pass variables with --opt KEY=VAL, and skip parts you do not want with --skip-extensions, --skip-completion, or --skip-repository.",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		featureName := args[0]

cmd/feature/list.go

@@ -11,6 +11,7 @@ import (
 var listCmd = &cobra.Command{
 	Use:     "list",
 	Short:   "List available features that can be installed",
+	Long:    "List the features you can install, marking where each comes from — the shipped set, a workspace override, or your own ~/.ws/features.d.",
 	Aliases: []string{"ls"},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		result, err := features.ListFeatures(featureDirs(cmd))

cmd/feature/store.go

@@ -12,6 +12,7 @@ import (
 var storeCmd = &cobra.Command{
 	Use:   "store",
 	Short: "List packages available in the feature store",
+	Long:  "List the artifacts published to the feature store (WS_FEATURES_STORE_URL) — the offline mirror features install from when the network is locked down.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		storeURL, _ := config.Resolve("features", "store_url")
 		if storeURL == "" {

cmd/info/env.go

@@ -33,6 +33,7 @@ func showEnvironment(writer io.Writer) {
 var envCmd = &cobra.Command{
 	Use:   "env",
 	Short: "Display effective workspace environment variables",
+	Long:  "Print every WS_* variable in effect, sorted — the resolved environment the workspace booted with.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		showEnvironment(cmd.OutOrStdout())
 		return nil

cmd/info/extensions.go

@@ -12,6 +12,7 @@ import (
 var extensionsCmd = &cobra.Command{
 	Use:   "extensions",
 	Short: "Display installed extensions",
+	Long:  "List the installed VS Code extensions with their versions.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		extensions, _ := config.GetExtensions()
 

cmd/info/info.go

@@ -36,11 +36,13 @@ func showVersion(writer io.Writer) {
 var InfoCmd = &cobra.Command{
 	Use:   "info",
 	Short: "Display workspace information",
+	Long:  "Report facts about the running workspace — version, effective environment, installed extensions, live resource metrics, and uptime.",
 }
 
 var showVersionCmd = &cobra.Command{
 	Use:   "version",
 	Short: "Display installed workspace version",
+	Long:  "Print the workspace version. --all expands to the full table — workspace, ws-cli, and VS Code.",
 	Run: func(cmd *cobra.Command, args []string) {
 		if all, _ := cmd.Flags().GetBool("all"); all {
 			showVersion(cmd.OutOrStdout())

cmd/info/metrics.go

@@ -12,6 +12,7 @@ import (
 var metricsCmd = &cobra.Command{
 	Use:   "metrics",
 	Short: "Display workspace metrics",
+	Long:  "Show live resource usage — CPU, memory, disk, and file descriptors, plus GPU with --gpu.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		includeGPU, _ := cmd.Flags().GetBool("gpu")
 

cmd/info/uptime.go

@@ -12,6 +12,7 @@ import (
 var uptimeCmd = &cobra.Command{
 	Use:   "uptime",
 	Short: "Display the workspace uptime",
+	Long:  "Show when the workspace session started and how long it has been running.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		started, running, err := config.GetSessionInfo()
 

cmd/log/log.go

@@ -10,6 +10,7 @@ import (
 var LogCmd = &cobra.Command{
 	Use:   "log",
 	Short: "Log messages",
+	Long:  "Emit styled, level-tagged log lines — the same formatting the startup scripts use. --pipe runs each line of piped input through the logger.",
 }
 
 var debugCmd = createCommand("debug", "debugging")
@@ -19,6 +20,7 @@ var warnCmd = createCommand("warn", "warning")
 var stampCmd = &cobra.Command{
 	Use:   "stamp",
 	Short: "Log the current timestamp",
+	Long:  "Print just the current timestamp in the workspace log style — handy for marking phases in a startup log.",
 	Args:  cobra.NoArgs,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		withPipe, _ := cmd.Flags().GetBool("pipe")
@@ -36,6 +38,7 @@ func createCommand(short, long string) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   fmt.Sprintf("%s message", short),
 		Short: fmt.Sprintf("Log %s messages", long),
+		Long:  fmt.Sprintf("Emit a log line at %s level in the workspace style — the same formatting the startup scripts use. --indent nests it under a preceding line, --stamp prefixes a timestamp.", short),
 		Args:  validate,
 		RunE:  execute(short),
 	}

cmd/logs/logs.go

@@ -17,6 +17,7 @@ var validLogTargets = []string{"main", "metrics", "docker", "auth_proxy", "cloud
 var LogsCmd = &cobra.Command{
 	Use:   "logs",
 	Short: "Retrieve workspace logs",
+	Long:  "Read a workspace daemon's log — the main log by default, or --target metrics|docker|auth_proxy|cloudflared. Filter by --level, limit with --tail, or stream live with --follow.",
 	Args:  cobra.NoArgs,
 	RunE:  execute,
 }

cmd/root.go

@@ -24,6 +24,7 @@ import (
 var rootCmd = &cobra.Command{
 	Use:           "ws-cli",
 	Short:         "⚡ CLI companion to charge the workspace batteries",
+	Long:          "The workspace command-line companion. Groups helpers for inspecting the running workspace, managing settings and secrets, driving the editor, and serving local assets — most are called by the startup scripts, all are yours in the terminal.",
 	Version:       "v" + info.Version,
 	Aliases:       []string{"ws"},
 	SilenceErrors: true,
@@ -32,6 +33,10 @@ var rootCmd = &cobra.Command{
 	},
 }
 
+func RootCmd() *cobra.Command {
+	return rootCmd
+}
+
 func Execute() {
 	ctx := context.Background()
 

cmd/secrets/decrypt.go

@@ -9,6 +9,7 @@ import (
 var decryptCmd = &cobra.Command{
 	Use:   "decrypt <encrypted|->",
 	Short: "Decrypt an encrypted value",
+	Long:  "Decrypt a value produced by encrypt, under the master key. Reads from the argument or stdin (-); writes the plaintext to stdout, or a file with --output.",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		cfg := getOutputConfig(cmd)

cmd/secrets/encrypt.go

@@ -12,6 +12,7 @@ import (
 var encryptCmd = &cobra.Command{
 	Use:   "encrypt <plaintext|->",
 	Short: "Encrypt a plaintext value",
+	Long:  "Encrypt a value under the master key. Reads the plaintext from the argument or stdin (-); writes the ciphertext to stdout, or a file with --output.",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		cfg := getOutputConfig(cmd)

cmd/secrets/generate.go

@@ -5,6 +5,7 @@ import "github.com/spf13/cobra"
 var generateCmd = &cobra.Command{
 	Use:   "generate",
 	Short: "Generate master keys or login password hashes",
+	Long:  "Generate the credentials the workspace needs — a master key for secrets, or a login password hash for the server.",
 }
 
 func init() {

cmd/secrets/login.go

@@ -13,6 +13,7 @@ import (
 var loginCmd = &cobra.Command{
 	Use:   "login",
 	Short: "Generate a workspace password hash for authentication",
+	Long:  "Prompt for a password and print its hash for the workspace server login (WS_AUTH_PASSWORD_HASHED). Store the hash, never the password.",
 	Args:  cobra.NoArgs,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		cfg := getOutputConfig(cmd)

cmd/secrets/master.go

@@ -14,6 +14,7 @@ import (
 var masterCmd = &cobra.Command{
 	Use:   "master",
 	Short: "Generate a cryptographically secure master key",
+	Long:  "Generate a random master key, printed base64-encoded — the key encrypt, decrypt, and the seed engine use. --length sets the byte size (default 32).",
 	Args:  cobra.NoArgs,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		cfg := getOutputConfig(cmd)

cmd/secrets/secrets.go

@@ -7,6 +7,7 @@ import (
 var SecretsCmd = &cobra.Command{
 	Use:   "secrets",
 	Short: "Manage encryption and decryption of secrets",
+	Long:  "Encrypt and decrypt values under a master key, and generate the keys themselves. Encrypted values are what the seed engine's secrets: map stores and decrypts at boot.",
 }
 
 func init() {

cmd/seed/apply.go

@@ -12,6 +12,7 @@ import (
 var applyCmd = &cobra.Command{
 	Use:          "apply [dest...]",
 	Short:        "Project seed content onto the filesystem",
+	Long:         "Apply the seed source to the filesystem — mirror bare files and run the .seed.yaml operations. Writes only where the destination is missing unless --force; pass destinations to limit the run to those paths.",
 	SilenceUsage: true,
 	RunE:         runApply,
 }

cmd/seed/ls.go

@@ -11,6 +11,7 @@ import (
 var lsCmd = &cobra.Command{
 	Use:   "ls",
 	Short: "List seed destinations and their behaviors",
+	Long:  "List what apply would write — each destination with its operation and whether it carries a secret or a template — without touching the filesystem.",
 	RunE:  runLs,
 }
 

cmd/seed/rotate.go

@@ -8,6 +8,7 @@ import (
 var rotateCmd = &cobra.Command{
 	Use:          "rotate",
 	Short:        "Re-encrypt managed secrets under a new master key",
+	Long:         "Re-encrypt every managed secret from the old master key (--master) to a new one (--new-master), in place. All-or-nothing: it verifies every secret decrypts before writing anything.",
 	SilenceUsage: true,
 	RunE:         runRotate,
 }

cmd/seed/seed.go

@@ -8,6 +8,7 @@ import (
 var SeedCmd = &cobra.Command{
 	Use:   "seed",
 	Short: "Project declarative content onto the filesystem",
+	Long:  "Copy files and apply small edits from a seed source onto the filesystem at boot. Bare files mirror verbatim; a .seed.yaml manifest overlays behavior — copy, merge, append — and decrypts secrets under the master key. Point --source at a mounted volume to seed a container from durable storage.",
 }
 
 func init() {

cmd/serve/current.go

@@ -12,6 +12,7 @@ import (
 var currentCmd = &cobra.Command{
 	Use:   "current",
 	Short: "Serve current directory as a static site",
+	Long:  "Serve the current directory over HTTP as a static site — a quick way to preview built files.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		port, _ := cmd.Flags().GetInt("port")
 		bind, _ := cmd.Flags().GetString("bind")

cmd/serve/font.go

@@ -11,6 +11,7 @@ import (
 var fontCmd = &cobra.Command{
 	Use:   "font",
 	Short: "Serve fonts for local download",
+	Long:  "Serve the installed fonts over HTTP so a browser can fetch them for local install.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		port, _ := cmd.Flags().GetInt("port")
 		bind, _ := cmd.Flags().GetString("bind")

cmd/serve/serve.go

@@ -5,6 +5,7 @@ import "github.com/spf13/cobra"
 var ServeCmd = &cobra.Command{
 	Use:   "serve",
 	Short: "Serve internal assets",
+	Long:  "Run a small HTTP server for local assets — fonts or the current directory — on --port (default 38080).",
 }
 
 func init() {

cmd/show/env.go

@@ -17,6 +17,7 @@ var osExit = os.Exit
 var envCmd = &cobra.Command{
 	Use:   "env <KEY>",
 	Short: "Display the resolved value of a workspace environment variable",
+	Long:  "Resolve a setting by its dotted key (server.port) and print it with its source and description. --value emits just the value for scripts, --as bool|int|list validates the shape, --check tests whether it is set so a startup script can guard on it.",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		dotted := args[0]

cmd/show/ip.go

@@ -9,12 +9,14 @@ import (
 var ipCmd = &cobra.Command{
 	Use:   "ip",
 	Short: "Display IP addresses",
+	Long:  "Print the workspace's IP addresses — the internal container address or the node it runs on.",
 }
 
-func makeIPCmd(use, short, title string, getter func() (string, error)) *cobra.Command {
+func makeIPCmd(use, short, long, title string, getter func() (string, error)) *cobra.Command {
 	return &cobra.Command{
 		Use:   use,
 		Short: short,
+		Long:  long,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ip, err := getter()
 			if err != nil {
@@ -36,8 +38,8 @@ func makeIPCmd(use, short, title string, getter func() (string, error)) *cobra.C
 
 func init() {
 	ipCmd.AddCommand(
-		makeIPCmd("internal", "Display the internal IP address", "Internal IP Address", net.GetInternalIP),
-		makeIPCmd("node", "Display the node/host IP address", "Node IP Address", net.GetNodeIP),
+		makeIPCmd("internal", "Display the internal IP address", "Print the workspace container's internal IP address.", "Internal IP Address", net.GetInternalIP),
+		makeIPCmd("node", "Display the node/host IP address", "Print the IP address of the node hosting the workspace.", "Node IP Address", net.GetNodeIP),
 	)
 
 	ShowCmd.AddCommand(ipCmd)

cmd/show/ip_test.go

@@ -11,7 +11,7 @@ import (
 
 func _runIPCmd(t *testing.T, title string, getter func() (string, error)) (stdout, stderr string, err error) {
 	t.Helper()
-	cmd := makeIPCmd("ip", "Display an IP address", title, getter)
+	cmd := makeIPCmd("ip", "Display an IP address", "", title, getter)
 
 	var outBuf, errBuf bytes.Buffer
 	cmd.SetOut(&outBuf)