feat: group CLI commands by server/management/client in help output
- commit
- a16d62c04f41b766f0b3ca019535a3dd28814ed1
- author
- brice · · 2026-01-17 15:54 UTC
- parent
- 22cea8c
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
2 files · +97 -24
M docs/cli/index.md +25 -7
| @@ -2,20 +2,38 @@ | |||
| 2 | 2 | ||
| 3 | 3 | Gordon provides a command-line interface for server management, deployment, and authentication. | |
| 4 | 4 | ||
| 5 | - | ## Commands Overview | |
| 5 | + | Commands are organized by where they run: | |
| 6 | + | ||
| 7 | + | - **Server Commands** - Must run on the machine hosting Gordon | |
| 8 | + | - **Management Commands** - Work locally or remotely via `--remote` flag | |
| 9 | + | - **Client Commands** - CLI utilities that don't require a running Gordon server | |
| 10 | + | ||
| 11 | + | ## Server Commands (local only) | |
| 6 | 12 | ||
| 7 | 13 | | Command | Description | Documentation | | |
| 8 | 14 | |---------|-------------|---------------| | |
| 9 | 15 | | `gordon serve` | Start the Gordon server | [serve](./serve.md) | | |
| 16 | + | | `gordon auth` | Manage Gordon server authentication | [auth](./auth.md) | | |
| 17 | + | ||
| 18 | + | ## Management Commands (local or --remote) | |
| 19 | + | ||
| 20 | + | | Command | Description | Documentation | | |
| 21 | + | |---------|-------------|---------------| | |
| 22 | + | | `gordon routes` | Manage routes | [routes](./routes.md) | | |
| 23 | + | | `gordon attachments` | Manage container attachments | [attachments](./attachments.md) | | |
| 24 | + | | `gordon secrets` | Manage secrets | [secrets](./secrets.md) | | |
| 25 | + | | `gordon deploy` | Manually deploy or redeploy a route | [serve](./serve.md#gordon-deploy) | | |
| 10 | 26 | | `gordon reload` | Reload configuration and sync containers | [serve](./serve.md#gordon-reload) | | |
| 11 | - | | `gordon deploy` | Manually deploy or redeploy a specific route | [serve](./serve.md#gordon-deploy) | | |
| 12 | 27 | | `gordon logs` | Display Gordon process or container logs | [serve](./serve.md#gordon-logs) | | |
| 13 | - | | `gordon version` | Print version information | [serve](./serve.md#gordon-version) | | |
| 14 | - | | `gordon auth` | Manage Gordon server authentication | [auth](./auth.md) | | |
| 15 | - | | `gordon routes` | Manage routes (local or remote) | [routes](./routes.md) | | |
| 16 | - | | `gordon attachments` | Manage attachments (local or remote) | [attachments](./attachments.md) | | |
| 17 | - | | `gordon secrets` | Manage secrets (local or remote) | [secrets](./secrets.md) | | |
| 28 | + | | `gordon status` | Show Gordon server status | - | | |
| 29 | + | ||
| 30 | + | ## Client Commands | |
| 31 | + | ||
| 32 | + | | Command | Description | Documentation | | |
| 33 | + | |---------|-------------|---------------| | |
| 18 | 34 | | `gordon remotes` | Manage saved remote Gordon instances | [remotes](./remotes.md) | | |
| 35 | + | | `gordon version` | Print version information | [serve](./serve.md#gordon-version) | | |
| 36 | + | | `gordon completion` | Generate shell autocompletion scripts | - | | |
| 19 | 37 | ||
| 20 | 38 | ## Quick Reference | |
| 21 | 39 | ||
| @@ -2,20 +2,38 @@ | |||||
| 2 | 2 | ||||
| 3 | Gordon provides a command-line interface for server management, deployment, and authentication. | 3 | Gordon provides a command-line interface for server management, deployment, and authentication. | ||
| 4 | 4 | ||||
| 5 | - | ## Commands Overview | 5 | + | Commands are organized by where they run: |
| 6 | + | ||||
| 7 | + | - **Server Commands** - Must run on the machine hosting Gordon | |||
| 8 | + | - **Management Commands** - Work locally or remotely via `--remote` flag | |||
| 9 | + | - **Client Commands** - CLI utilities that don't require a running Gordon server | |||
| 10 | + | ||||
| 11 | + | ## Server Commands (local only) | |||
| 6 | 12 | ||||
| 7 | | Command | Description | Documentation | | 13 | | Command | Description | Documentation | | ||
| 8 | |---------|-------------|---------------| | 14 | |---------|-------------|---------------| | ||
| 9 | | `gordon serve` | Start the Gordon server | [serve](./serve.md) | | 15 | | `gordon serve` | Start the Gordon server | [serve](./serve.md) | | ||
| 16 | + | | `gordon auth` | Manage Gordon server authentication | [auth](./auth.md) | | |||
| 17 | + | ||||
| 18 | + | ## Management Commands (local or --remote) | |||
| 19 | + | ||||
| 20 | + | | Command | Description | Documentation | | |||
| 21 | + | |---------|-------------|---------------| | |||
| 22 | + | | `gordon routes` | Manage routes | [routes](./routes.md) | | |||
| 23 | + | | `gordon attachments` | Manage container attachments | [attachments](./attachments.md) | | |||
| 24 | + | | `gordon secrets` | Manage secrets | [secrets](./secrets.md) | | |||
| 25 | + | | `gordon deploy` | Manually deploy or redeploy a route | [serve](./serve.md#gordon-deploy) | | |||
| 10 | | `gordon reload` | Reload configuration and sync containers | [serve](./serve.md#gordon-reload) | | 26 | | `gordon reload` | Reload configuration and sync containers | [serve](./serve.md#gordon-reload) | | ||
| 11 | - | | `gordon deploy` | Manually deploy or redeploy a specific route | [serve](./serve.md#gordon-deploy) | | |||
| 12 | | `gordon logs` | Display Gordon process or container logs | [serve](./serve.md#gordon-logs) | | 27 | | `gordon logs` | Display Gordon process or container logs | [serve](./serve.md#gordon-logs) | | ||
| 13 | - | | `gordon version` | Print version information | [serve](./serve.md#gordon-version) | | 28 | + | | `gordon status` | Show Gordon server status | - | |
| 14 | - | | `gordon auth` | Manage Gordon server authentication | [auth](./auth.md) | | 29 | + | |
| 15 | - | | `gordon routes` | Manage routes (local or remote) | [routes](./routes.md) | | 30 | + | ## Client Commands |
| 16 | - | | `gordon attachments` | Manage attachments (local or remote) | [attachments](./attachments.md) | | 31 | + | |
| 17 | - | | `gordon secrets` | Manage secrets (local or remote) | [secrets](./secrets.md) | | 32 | + | | Command | Description | Documentation | |
| 33 | + | |---------|-------------|---------------| | |||
| 18 | | `gordon remotes` | Manage saved remote Gordon instances | [remotes](./remotes.md) | | 34 | | `gordon remotes` | Manage saved remote Gordon instances | [remotes](./remotes.md) | | ||
| 35 | + | | `gordon version` | Print version information | [serve](./serve.md#gordon-version) | | |||
| 36 | + | | `gordon completion` | Generate shell autocompletion scripts | - | | |||
| 19 | 37 | ||||
| 20 | ## Quick Reference | 38 | ## Quick Reference | ||
| 21 | 39 | ||||
M internal/adapters/in/cli/root.go +72 -17
| @@ -23,6 +23,13 @@ var ( | |||
| 23 | 23 | tokenFlag string | |
| 24 | 24 | ) | |
| 25 | 25 | ||
| 26 | + | // Command group IDs | |
| 27 | + | const ( | |
| 28 | + | groupServer = "server" | |
| 29 | + | groupManage = "manage" | |
| 30 | + | groupClient = "client" | |
| 31 | + | ) | |
| 32 | + | ||
| 26 | 33 | // NewRootCmd creates the root command for Gordon CLI. | |
| 27 | 34 | func NewRootCmd() *cobra.Command { | |
| 28 | 35 | rootCmd := &cobra.Command{ | |
| @@ -34,29 +41,77 @@ a Docker registry with automatic container deployment capabilities. | |||
| 34 | 41 | It listens for image pushes and automatically deploys containers based on | |
| 35 | 42 | configuration rules, making it ideal for single-server deployments. | |
| 36 | 43 | ||
| 37 | - | The CLI can target remote Gordon instances using the --remote flag or | |
| 38 | - | GORDON_REMOTE environment variable.`, | |
| 44 | + | Commands are organized by where they run: | |
| 45 | + | Server-only: Run on the machine hosting Gordon (serve, auth, reload) | |
| 46 | + | Management: Work locally or remotely via --remote flag (routes, secrets, etc.) | |
| 47 | + | Client-only: CLI utilities that don't require a running Gordon server`, | |
| 39 | 48 | } | |
| 40 | 49 | ||
| 50 | + | // Define command groups (order matters for help output) | |
| 51 | + | rootCmd.AddGroup( | |
| 52 | + | &cobra.Group{ID: groupServer, Title: "Server Commands (local only):"}, | |
| 53 | + | &cobra.Group{ID: groupManage, Title: "Management Commands (local or --remote):"}, | |
| 54 | + | &cobra.Group{ID: groupClient, Title: "Client Commands:"}, | |
| 55 | + | ) | |
| 56 | + | ||
| 41 | 57 | // Add persistent flags for remote targeting | |
| 42 | 58 | rootCmd.PersistentFlags().StringVar(&remoteFlag, "remote", "", "Remote Gordon URL (e.g., https://gordon.mydomain.com)") | |
| 43 | 59 | rootCmd.PersistentFlags().StringVar(&tokenFlag, "token", "", "Authentication token for remote") | |
| 44 | 60 | ||
| 45 | - | // Server commands | |
| 46 | - | rootCmd.AddCommand(newServeCmd()) | |
| 47 | - | rootCmd.AddCommand(newStartCmd()) // Deprecated alias for serve | |
| 48 | - | rootCmd.AddCommand(newReloadCmd()) | |
| 49 | - | rootCmd.AddCommand(newDeployCmd()) | |
| 50 | - | rootCmd.AddCommand(newLogsCmd()) | |
| 51 | - | rootCmd.AddCommand(newVersionCmd()) | |
| 52 | - | rootCmd.AddCommand(newAuthCmd()) | |
| 53 | - | ||
| 54 | - | // Remote management commands | |
| 55 | - | rootCmd.AddCommand(newRoutesCmd()) | |
| 56 | - | rootCmd.AddCommand(newAttachmentsCmd()) | |
| 57 | - | rootCmd.AddCommand(newSecretsCmd()) | |
| 58 | - | rootCmd.AddCommand(newRemotesCmd()) | |
| 59 | - | rootCmd.AddCommand(newStatusCmd()) | |
| 61 | + | // Server-only commands (must run on the Gordon host) | |
| 62 | + | serveCmd := newServeCmd() | |
| 63 | + | serveCmd.GroupID = groupServer | |
| 64 | + | rootCmd.AddCommand(serveCmd) | |
| 65 | + | ||
| 66 | + | startCmd := newStartCmd() // Deprecated alias for serve | |
| 67 | + | startCmd.GroupID = groupServer | |
| 68 | + | rootCmd.AddCommand(startCmd) | |
| 69 | + | ||
| 70 | + | authCmd := newAuthCmd() | |
| 71 | + | authCmd.GroupID = groupServer | |
| 72 | + | rootCmd.AddCommand(authCmd) | |
| 73 | + | ||
| 74 | + | // Management commands (work locally or via --remote) | |
| 75 | + | routesCmd := newRoutesCmd() | |
| 76 | + | routesCmd.GroupID = groupManage | |
| 77 | + | rootCmd.AddCommand(routesCmd) | |
| 78 | + | ||
| 79 | + | attachmentsCmd := newAttachmentsCmd() | |
| 80 | + | attachmentsCmd.GroupID = groupManage | |
| 81 | + | rootCmd.AddCommand(attachmentsCmd) | |
| 82 | + | ||
| 83 | + | secretsCmd := newSecretsCmd() | |
| 84 | + | secretsCmd.GroupID = groupManage | |
| 85 | + | rootCmd.AddCommand(secretsCmd) | |
| 86 | + | ||
| 87 | + | deployCmd := newDeployCmd() | |
| 88 | + | deployCmd.GroupID = groupManage | |
| 89 | + | rootCmd.AddCommand(deployCmd) | |
| 90 | + | ||
| 91 | + | reloadCmd := newReloadCmd() | |
| 92 | + | reloadCmd.GroupID = groupManage | |
| 93 | + | rootCmd.AddCommand(reloadCmd) | |
| 94 | + | ||
| 95 | + | logsCmd := newLogsCmd() | |
| 96 | + | logsCmd.GroupID = groupManage | |
| 97 | + | rootCmd.AddCommand(logsCmd) | |
| 98 | + | ||
| 99 | + | statusCmd := newStatusCmd() | |
| 100 | + | statusCmd.GroupID = groupManage | |
| 101 | + | rootCmd.AddCommand(statusCmd) | |
| 102 | + | ||
| 103 | + | // Client-only commands (no server needed) | |
| 104 | + | remotesCmd := newRemotesCmd() | |
| 105 | + | remotesCmd.GroupID = groupClient | |
| 106 | + | rootCmd.AddCommand(remotesCmd) | |
| 107 | + | ||
| 108 | + | versionCmd := newVersionCmd() | |
| 109 | + | versionCmd.GroupID = groupClient | |
| 110 | + | rootCmd.AddCommand(versionCmd) | |
| 111 | + | ||
| 112 | + | // Put help and completion in the client group | |
| 113 | + | rootCmd.SetHelpCommandGroupID(groupClient) | |
| 114 | + | rootCmd.SetCompletionCommandGroupID(groupClient) | |
| 60 | 115 | ||
| 61 | 116 | return rootCmd | |
| 62 | 117 | } | |
| @@ -23,6 +23,13 @@ var ( | |||||
| 23 | tokenFlag string | 23 | tokenFlag string | ||
| 24 | ) | 24 | ) | ||
| 25 | 25 | ||||
| 26 | + | // Command group IDs | |||
| 27 | + | const ( | |||
| 28 | + | groupServer = "server" | |||
| 29 | + | groupManage = "manage" | |||
| 30 | + | groupClient = "client" | |||
| 31 | + | ) | |||
| 32 | + | ||||
| 26 | // NewRootCmd creates the root command for Gordon CLI. | 33 | // NewRootCmd creates the root command for Gordon CLI. | ||
| 27 | func NewRootCmd() *cobra.Command { | 34 | func NewRootCmd() *cobra.Command { | ||
| 28 | rootCmd := &cobra.Command{ | 35 | rootCmd := &cobra.Command{ | ||
| @@ -34,29 +41,77 @@ a Docker registry with automatic container deployment capabilities. | |||||
| 34 | It listens for image pushes and automatically deploys containers based on | 41 | It listens for image pushes and automatically deploys containers based on | ||
| 35 | configuration rules, making it ideal for single-server deployments. | 42 | configuration rules, making it ideal for single-server deployments. | ||
| 36 | 43 | ||||
| 37 | - | The CLI can target remote Gordon instances using the --remote flag or | 44 | + | Commands are organized by where they run: |
| 38 | - | GORDON_REMOTE environment variable.`, | 45 | + | Server-only: Run on the machine hosting Gordon (serve, auth, reload) |
| 46 | + | Management: Work locally or remotely via --remote flag (routes, secrets, etc.) | |||
| 47 | + | Client-only: CLI utilities that don't require a running Gordon server`, | |||
| 39 | } | 48 | } | ||
| 40 | 49 | ||||
| 50 | + | // Define command groups (order matters for help output) | |||
| 51 | + | rootCmd.AddGroup( | |||
| 52 | + | &cobra.Group{ID: groupServer, Title: "Server Commands (local only):"}, | |||
| 53 | + | &cobra.Group{ID: groupManage, Title: "Management Commands (local or --remote):"}, | |||
| 54 | + | &cobra.Group{ID: groupClient, Title: "Client Commands:"}, | |||
| 55 | + | ) | |||
| 56 | + | ||||
| 41 | // Add persistent flags for remote targeting | 57 | // Add persistent flags for remote targeting | ||
| 42 | rootCmd.PersistentFlags().StringVar(&remoteFlag, "remote", "", "Remote Gordon URL (e.g., https://gordon.mydomain.com)") | 58 | rootCmd.PersistentFlags().StringVar(&remoteFlag, "remote", "", "Remote Gordon URL (e.g., https://gordon.mydomain.com)") | ||
| 43 | rootCmd.PersistentFlags().StringVar(&tokenFlag, "token", "", "Authentication token for remote") | 59 | rootCmd.PersistentFlags().StringVar(&tokenFlag, "token", "", "Authentication token for remote") | ||
| 44 | 60 | ||||
| 45 | - | // Server commands | 61 | + | // Server-only commands (must run on the Gordon host) |
| 46 | - | rootCmd.AddCommand(newServeCmd()) | 62 | + | serveCmd := newServeCmd() |
| 47 | - | rootCmd.AddCommand(newStartCmd()) // Deprecated alias for serve | 63 | + | serveCmd.GroupID = groupServer |
| 48 | - | rootCmd.AddCommand(newReloadCmd()) | 64 | + | rootCmd.AddCommand(serveCmd) |
| 49 | - | rootCmd.AddCommand(newDeployCmd()) | 65 | + | |
| 50 | - | rootCmd.AddCommand(newLogsCmd()) | 66 | + | startCmd := newStartCmd() // Deprecated alias for serve |
| 51 | - | rootCmd.AddCommand(newVersionCmd()) | 67 | + | startCmd.GroupID = groupServer |
| 52 | - | rootCmd.AddCommand(newAuthCmd()) | 68 | + | rootCmd.AddCommand(startCmd) |
| 53 | - | 69 | + | ||
| 54 | - | // Remote management commands | 70 | + | authCmd := newAuthCmd() |
| 55 | - | rootCmd.AddCommand(newRoutesCmd()) | 71 | + | authCmd.GroupID = groupServer |
| 56 | - | rootCmd.AddCommand(newAttachmentsCmd()) | 72 | + | rootCmd.AddCommand(authCmd) |
| 57 | - | rootCmd.AddCommand(newSecretsCmd()) | 73 | + | |
| 58 | - | rootCmd.AddCommand(newRemotesCmd()) | 74 | + | // Management commands (work locally or via --remote) |
| 59 | - | rootCmd.AddCommand(newStatusCmd()) | 75 | + | routesCmd := newRoutesCmd() |
| 76 | + | routesCmd.GroupID = groupManage | |||
| 77 | + | rootCmd.AddCommand(routesCmd) | |||
| 78 | + | ||||
| 79 | + | attachmentsCmd := newAttachmentsCmd() | |||
| 80 | + | attachmentsCmd.GroupID = groupManage | |||
| 81 | + | rootCmd.AddCommand(attachmentsCmd) | |||
| 82 | + | ||||
| 83 | + | secretsCmd := newSecretsCmd() | |||
| 84 | + | secretsCmd.GroupID = groupManage | |||
| 85 | + | rootCmd.AddCommand(secretsCmd) | |||
| 86 | + | ||||
| 87 | + | deployCmd := newDeployCmd() | |||
| 88 | + | deployCmd.GroupID = groupManage | |||
| 89 | + | rootCmd.AddCommand(deployCmd) | |||
| 90 | + | ||||
| 91 | + | reloadCmd := newReloadCmd() | |||
| 92 | + | reloadCmd.GroupID = groupManage | |||
| 93 | + | rootCmd.AddCommand(reloadCmd) | |||
| 94 | + | ||||
| 95 | + | logsCmd := newLogsCmd() | |||
| 96 | + | logsCmd.GroupID = groupManage | |||
| 97 | + | rootCmd.AddCommand(logsCmd) | |||
| 98 | + | ||||
| 99 | + | statusCmd := newStatusCmd() | |||
| 100 | + | statusCmd.GroupID = groupManage | |||
| 101 | + | rootCmd.AddCommand(statusCmd) | |||
| 102 | + | ||||
| 103 | + | // Client-only commands (no server needed) | |||
| 104 | + | remotesCmd := newRemotesCmd() | |||
| 105 | + | remotesCmd.GroupID = groupClient | |||
| 106 | + | rootCmd.AddCommand(remotesCmd) | |||
| 107 | + | ||||
| 108 | + | versionCmd := newVersionCmd() | |||
| 109 | + | versionCmd.GroupID = groupClient | |||
| 110 | + | rootCmd.AddCommand(versionCmd) | |||
| 111 | + | ||||
| 112 | + | // Put help and completion in the client group | |||
| 113 | + | rootCmd.SetHelpCommandGroupID(groupClient) | |||
| 114 | + | rootCmd.SetCompletionCommandGroupID(groupClient) | |||
| 60 | 115 | ||||
| 61 | return rootCmd | 116 | return rootCmd | ||
| 62 | } | 117 | } | ||