feat(cmd): add workspace start and stop commands (#70)

README.md

@@ -120,7 +120,35 @@ $ kortex-cli workspace list -o json
 
 Exit code: `0` (success)
 
-**Step 5: Remove a workspace**
+**Step 5: Start a workspace**
+
+```bash
+$ kortex-cli workspace start 2c5f16046476be368fcada501ac6cdc6bbd34ea80eb9ceb635530c0af64681ea -o json
+```
+
+```json
+{
+  "id": "2c5f16046476be368fcada501ac6cdc6bbd34ea80eb9ceb635530c0af64681ea"
+}
+```
+
+Exit code: `0` (success)
+
+**Step 6: Stop a workspace**
+
+```bash
+$ kortex-cli workspace stop 2c5f16046476be368fcada501ac6cdc6bbd34ea80eb9ceb635530c0af64681ea -o json
+```
+
+```json
+{
+  "id": "2c5f16046476be368fcada501ac6cdc6bbd34ea80eb9ceb635530c0af64681ea"
+}
+```
+
+Exit code: `0` (success)
+
+**Step 7: Remove a workspace**
 
 ```bash
 $ kortex-cli workspace remove 2c5f16046476be368fcada501ac6cdc6bbd34ea80eb9ceb635530c0af64681ea -o json
@@ -134,7 +162,7 @@ $ kortex-cli workspace remove 2c5f16046476be368fcada501ac6cdc6bbd34ea80eb9ceb635
 
 Exit code: `0` (success)
 
-**Step 6: Verify removal**
+**Step 8: Verify removal**
 
 ```bash
 $ kortex-cli workspace list -o json
@@ -498,6 +526,188 @@ kortex-cli list -o json
 - All paths are displayed as absolute paths for consistency
 - **JSON error handling**: When `--output json` is used, errors are written to stdout (not stderr) in JSON format, and the CLI exits with code 1. Always check the exit code to determine success/failure
 
+### `workspace start` - Start a Workspace
+
+Starts a registered workspace by its ID. Also available as the shorter alias `start`.
+
+#### Usage
+
+```bash
+kortex-cli workspace start ID [flags]
+kortex-cli start ID [flags]
+```
+
+#### Arguments
+
+- `ID` - The unique identifier of the workspace to start (required)
+
+#### Flags
+
+- `--output, -o <format>` - Output format (supported: `json`)
+- `--storage <path>` - Storage directory for kortex-cli data (default: `$HOME/.kortex-cli`)
+
+#### Examples
+
+**Start a workspace by ID:**
+```bash
+kortex-cli workspace start a1b2c3d4e5f6...
+```
+Output: `a1b2c3d4e5f6...` (ID of started workspace)
+
+**Use the short alias:**
+```bash
+kortex-cli start a1b2c3d4e5f6...
+```
+
+**View workspace IDs before starting:**
+```bash
+# First, list all workspaces to find the ID
+kortex-cli list
+
+# Then start the desired workspace
+kortex-cli start a1b2c3d4e5f6...
+```
+
+**JSON output:**
+```bash
+kortex-cli workspace start a1b2c3d4e5f6... --output json
+```
+Output:
+```json
+{
+  "id": "a1b2c3d4e5f6..."
+}
+```
+
+**JSON output with short flag:**
+```bash
+kortex-cli start a1b2c3d4e5f6... -o json
+```
+
+#### Error Handling
+
+**Workspace not found (text format):**
+```bash
+kortex-cli start invalid-id
+```
+Output:
+```text
+Error: workspace not found: invalid-id
+Use 'workspace list' to see available workspaces
+```
+
+**Workspace not found (JSON format):**
+```bash
+kortex-cli start invalid-id --output json
+```
+Output:
+```json
+{
+  "error": "workspace not found: invalid-id"
+}
+```
+
+#### Notes
+
+- The workspace ID is required and can be obtained using the `workspace list` or `list` command
+- Starting a workspace launches its associated runtime instance
+- Upon successful start, the command outputs the ID of the started workspace
+- The workspace runtime state is updated to reflect that it's running
+- JSON output format is useful for scripting and automation
+- When using `--output json`, errors are also returned in JSON format for consistent parsing
+- **JSON error handling**: When `--output json` is used, errors are written to stdout (not stderr) in JSON format, and the CLI exits with code 1. Always check the exit code to determine success/failure
+
+### `workspace stop` - Stop a Workspace
+
+Stops a running workspace by its ID. Also available as the shorter alias `stop`.
+
+#### Usage
+
+```bash
+kortex-cli workspace stop ID [flags]
+kortex-cli stop ID [flags]
+```
+
+#### Arguments
+
+- `ID` - The unique identifier of the workspace to stop (required)
+
+#### Flags
+
+- `--output, -o <format>` - Output format (supported: `json`)
+- `--storage <path>` - Storage directory for kortex-cli data (default: `$HOME/.kortex-cli`)
+
+#### Examples
+
+**Stop a workspace by ID:**
+```bash
+kortex-cli workspace stop a1b2c3d4e5f6...
+```
+Output: `a1b2c3d4e5f6...` (ID of stopped workspace)
+
+**Use the short alias:**
+```bash
+kortex-cli stop a1b2c3d4e5f6...
+```
+
+**View workspace IDs before stopping:**
+```bash
+# First, list all workspaces to find the ID
+kortex-cli list
+
+# Then stop the desired workspace
+kortex-cli stop a1b2c3d4e5f6...
+```
+
+**JSON output:**
+```bash
+kortex-cli workspace stop a1b2c3d4e5f6... --output json
+```
+Output:
+```json
+{
+  "id": "a1b2c3d4e5f6..."
+}
+```
+
+**JSON output with short flag:**
+```bash
+kortex-cli stop a1b2c3d4e5f6... -o json
+```
+
+#### Error Handling
+
+**Workspace not found (text format):**
+```bash
+kortex-cli stop invalid-id
+```
+Output:
+```text
+Error: workspace not found: invalid-id
+Use 'workspace list' to see available workspaces
+```
+
+**Workspace not found (JSON format):**
+```bash
+kortex-cli stop invalid-id --output json
+```
+Output:
+```json
+{
+  "error": "workspace not found: invalid-id"
+}
+```
+
+#### Notes
+
+- The workspace ID is required and can be obtained using the `workspace list` or `list` command
+- Stopping a workspace stops its associated runtime instance
+- Upon successful stop, the command outputs the ID of the stopped workspace
+- The workspace runtime state is updated to reflect that it's stopped
+- JSON output format is useful for scripting and automation
+- When using `--output json`, errors are also returned in JSON format for consistent parsing
+- **JSON error handling**: When `--output json` is used, errors are written to stdout (not stderr) in JSON format, and the CLI exits with code 1. Always check the exit code to determine success/failure
+
 ### `workspace remove` - Remove a Workspace
 
 Removes a registered workspace by its ID. Also available as the shorter alias `remove`.

pkg/cmd/root.go

@@ -50,6 +50,8 @@ func NewRootCmd() *cobra.Command {
 	rootCmd.AddCommand(NewWorkspaceCmd())
 	rootCmd.AddCommand(NewListCmd())
 	rootCmd.AddCommand(NewRemoveCmd())
+	rootCmd.AddCommand(NewStartCmd())
+	rootCmd.AddCommand(NewStopCmd())
 
 	// Global flags
 	rootCmd.PersistentFlags().String("storage", defaultStoragePath, "Directory where kortex-cli will store all its files")

pkg/cmd/start.go

@@ -0,0 +1,44 @@
+/**********************************************************************
+ * Copyright (C) 2026 Red Hat, Inc.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ **********************************************************************/
+
+package cmd
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func NewStartCmd() *cobra.Command {
+	// Create the workspace start command
+	workspaceStartCmd := NewWorkspaceStartCmd()
+
+	// Create an alias command that delegates to workspace start
+	cmd := &cobra.Command{
+		Use:     "start ID",
+		Short:   workspaceStartCmd.Short,
+		Long:    workspaceStartCmd.Long,
+		Example: AdaptExampleForAlias(workspaceStartCmd.Example, "workspace start", "start"),
+		Args:    workspaceStartCmd.Args,
+		PreRunE: workspaceStartCmd.PreRunE,
+		RunE:    workspaceStartCmd.RunE,
+	}
+
+	// Copy flags from workspace start command
+	cmd.Flags().AddFlagSet(workspaceStartCmd.Flags())
+
+	return cmd
+}

pkg/cmd/stop.go

@@ -0,0 +1,44 @@
+/**********************************************************************
+ * Copyright (C) 2026 Red Hat, Inc.
+ *
+ * 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ **********************************************************************/
+
+package cmd
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func NewStopCmd() *cobra.Command {
+	// Create the workspace stop command
+	workspaceStopCmd := NewWorkspaceStopCmd()
+
+	// Create an alias command that delegates to workspace stop
+	cmd := &cobra.Command{
+		Use:     "stop ID",
+		Short:   workspaceStopCmd.Short,
+		Long:    workspaceStopCmd.Long,
+		Example: AdaptExampleForAlias(workspaceStopCmd.Example, "workspace stop", "stop"),
+		Args:    workspaceStopCmd.Args,
+		PreRunE: workspaceStopCmd.PreRunE,
+		RunE:    workspaceStopCmd.RunE,
+	}
+
+	// Copy flags from workspace stop command
+	cmd.Flags().AddFlagSet(workspaceStopCmd.Flags())
+
+	return cmd
+}

pkg/cmd/workspace.go

@@ -33,6 +33,8 @@ func NewWorkspaceCmd() *cobra.Command {
 	// Add subcommands
 	cmd.AddCommand(NewWorkspaceListCmd())
 	cmd.AddCommand(NewWorkspaceRemoveCmd())
+	cmd.AddCommand(NewWorkspaceStartCmd())
+	cmd.AddCommand(NewWorkspaceStopCmd())
 
 	return cmd
 }