CLI Reference

Workspace Manager Command-Line Client

Workspace Manager publishes a command-line client that can be used to script or automate various features.

Beta Software

IMPORTANT: The CLI is currently in beta, with limited features. Additional features will be added over time before GA release. The various sub-commands, options, and requirements are subject to change as the CLI matures.

Prerequisites

• Node.js 18 or later
• NPM 8 or later

Installation

There are two ways to run the WSM CLI: install it globally with npm or run it with npx.

Option 1: Global Installation with npm

npm install --global @ordinlabs/wsm-cli

After installation, you can run the CLI as wsm-cli:

wsm-cli --help

Option 2: Run with npx (No Installation)

npx @ordinlabs/wsm-cli --help

Tip

npx is fine for occasional use but it can be slow. We recommend installing wsm globally if you intend to run it with some frequency.

Global Options

These options are available for all commands:

Option	Description	Default
-c, --config <path>	Set config path	~/.wsm/credentials.yaml
-p, --profile <name>	Set profile name to use from config	default
-v, --verbose	Enable verbose logging	-
-V, --version	Output the version number	-
-h, --help	Display help for command	-

Commands Overview

wsm-cli [options] [command]

Commands:
  login         Log into WSM CLI
  project       Project management commands
  workspace     Workspace management commands
  ssh           SSH management commands
  config        Edit config values of the CLI
  help          Display help for command

---

Authentication

login

Log into WSM CLI and generate an API token.

wsm-cli login [options]

Options:

Option	Description	Default
-u, --base-url <baseurl>	Set base URL of the WSM	-
-f, --force	Force replacement of credentials	-

Examples:

# Interactive login
wsm-cli login

# Login with specific base URL
wsm-cli login --base-url https://wsm.example.com

# Force regenerate token
wsm-cli login --force

The login command will prompt you for the base URL of your WSM admin (e.g., https://wsm.example.com) and open a browser for authentication.

Token Expiration

The default expiration for tokens generated with the login command is 30 days. If you need a key for longer, you will have to manually generate one in your profile.

---

Project Management

project list

List all projects you have access to.

wsm-cli project list [options]

Options:

Option	Description
-o, --output <format>	Output format (table, json, csv)

Examples:

# List all projects
wsm-cli project list

# List projects as JSON
wsm-cli project list --output json

project inspect

Inspect details of a specific project.

wsm-cli project inspect [options] <projectId>

Arguments:

• <projectId> - The ID of the project to inspect

Options:

Option	Description
-o, --output <format>	Output format (table, json, yaml)

Examples:

# Inspect a project
wsm-cli project inspect proj_abc123

# Get project details as JSON
wsm-cli project inspect proj_abc123 --output json

project delete

Delete a project.

wsm-cli project delete [options] <projectId>

Arguments:

• <projectId> - The ID of the project to delete

Options:

Option	Description
-f, --force	Skip confirmation prompt

Examples:

# Delete a project (with confirmation)
wsm-cli project delete proj_abc123

# Delete without confirmation
wsm-cli project delete proj_abc123 --force

Caution

Deleting a project will also delete all workspaces within that project. This action cannot be undone.

---

Workspace Management

workspace list

List all available workspaces.

wsm-cli workspace list [options]

Options:

Option	Description
-o, --output <format>	Output format (table, json, csv)
-p, --project <projectId>	Filter by project ID

Examples:

# List all workspaces
wsm-cli workspace list

# List workspaces in a specific project
wsm-cli workspace list --project proj_abc123

# List workspaces as JSON
wsm-cli workspace list --output json

workspace inspect

Display the status and details of a workspace.

wsm-cli workspace inspect [options] <workspaceId>

Arguments:

• <workspaceId> - The ID of the workspace to inspect

Options:

Option	Description
-o, --output <format>	Output format (table, json, yaml)

Examples:

# Inspect a workspace
wsm-cli workspace inspect ws_xyz789

# Get workspace details as JSON
wsm-cli workspace inspect ws_xyz789 --output json

workspace start

Start a workspace if it isn’t currently running.

wsm-cli workspace start [options] <workspaceId>

Arguments:

• <workspaceId> - The ID of the workspace to start

Options:

Option	Description
-w, --wait	Wait for workspace to be fully started
--timeout <seconds>	Timeout for wait operation

Examples:

# Start a workspace
wsm-cli workspace start ws_xyz789

# Start and wait for it to be ready
wsm-cli workspace start ws_xyz789 --wait

# Start with custom timeout
wsm-cli workspace start ws_xyz789 --wait --timeout 300

workspace stop

Stop a running workspace.

wsm-cli workspace stop [options] <workspaceId>

Arguments:

• <workspaceId> - The ID of the workspace to stop

Options:

Option	Description
-w, --wait	Wait for workspace to be fully stopped
--timeout <seconds>	Timeout for wait operation

Examples:

# Stop a workspace
wsm-cli workspace stop ws_xyz789

# Stop and wait for confirmation
wsm-cli workspace stop ws_xyz789 --wait

workspace delete

Delete a workspace.

wsm-cli workspace delete [options] <workspaceId>

Arguments:

• <workspaceId> - The ID of the workspace to delete

Options:

Option	Description
-f, --force	Skip confirmation prompt

Examples:

# Delete a workspace (with confirmation)
wsm-cli workspace delete ws_xyz789

# Delete without confirmation
wsm-cli workspace delete ws_xyz789 --force

Caution

Deleting a workspace will permanently remove all data. This action cannot be undone.

---

SSH Management

ssh config-update

Download and update your SSH configuration from WSM.

wsm-cli ssh config-update [options]

Options:

Option	Description
--dry-run	Show what would be updated without making changes

Examples:

# Update SSH config
wsm-cli ssh config-update

# Preview changes without applying
wsm-cli ssh config-update --dry-run

This command will:

1. Download your personalized SSH configuration
2. Save it to ~/.ssh/config.d/wsm-config
3. Update your ~/.ssh/config to include the WSM configuration

ssh autocomplete setup

Set up SSH autocomplete for your shell.

wsm-cli ssh autocomplete setup

This command will provide instructions for setting up autocomplete in your shell (Bash, Zsh, Fish, or PowerShell).

Examples:

# Set up autocomplete
wsm-cli ssh autocomplete setup

Follow the on-screen instructions to add the autocomplete script to your shell configuration.

Existing Autocomplete

If you are using an existing autocomplete for the ssh command, you will need to remove it before using the wsm-cli ssh autocomplete implementation.

ssh autocomplete generate

Generate autocomplete suggestions (used internally by shell completion).

wsm-cli ssh autocomplete generate [options]

Options:

Option	Description
--current <word>	Current word being completed
--previous <word>	Previous word in command line

This command is typically called by your shell’s completion system and not used directly.

---

Configuration Management

config show

Display current CLI configuration.

wsm-cli config show [options]

Options:

Option	Description
-o, --output <format>	Output format (yaml, json)

Examples:

# Show config
wsm-cli config show

# Show config as JSON
wsm-cli config show --output json

config set

Set a configuration value.

wsm-cli config set <key> <value>

Arguments:

• <key> - Configuration key to set
• <value> - Value to set

Examples:

# Set base URL
wsm-cli config set baseUrl https://wsm.example.com

# Set default profile
wsm-cli config set defaultProfile production

---

Configuration File

The CLI stores configuration in ~/.wsm/credentials.yaml by default.

File Structure

default:
  baseUrl: https://wsm.example.com
  token: your-api-token-here

production:
  baseUrl: https://wsm-prod.example.com
  token: prod-token-here

Using Profiles

You can maintain multiple profiles for different environments:

# Use default profile
wsm-cli workspace list

# Use production profile
wsm-cli --profile production workspace list

# Use custom config file
wsm-cli --config ~/my-wsm-config.yaml workspace list

---

Output Formats

Most commands support multiple output formats:

Table (Default)

Human-readable table format:

wsm-cli workspace list

JSON

Machine-readable JSON format:

wsm-cli workspace list --output json

CSV

Comma-separated values for spreadsheets:

wsm-cli workspace list --output csv

YAML

YAML format for configuration:

wsm-cli project inspect proj_abc123 --output yaml

---

Scripting Examples

Start All Stopped Workspaces

#!/bin/bash

# Get all workspaces as JSON
workspaces=$(wsm-cli workspace list --output json)

# Parse and start each stopped workspace
echo "$workspaces" | jq -r '.[] | select(.status == "stopped") | .id' | while read ws_id; do
  echo "Starting workspace: $ws_id"
  wsm-cli workspace start "$ws_id"
done

Daily Workspace Report

#!/bin/bash

# Generate daily report
echo "Workspace Status Report - $(date)"
echo "================================"
echo ""

# List all workspaces
wsm-cli workspace list --output table

# Count by status
echo ""
echo "Summary:"
wsm-cli workspace list --output json | jq -r 'group_by(.status) | .[] | "\(.[0].status): \(length)"'

Cleanup Old Workspaces

#!/bin/bash

# Delete workspaces older than 30 days
wsm-cli workspace list --output json | \
  jq -r '.[] | select(.lastUsed < (now - 2592000)) | .id' | \
  while read ws_id; do
    echo "Deleting old workspace: $ws_id"
    wsm-cli workspace delete "$ws_id" --force
  done

---

Error Handling

The CLI uses standard exit codes:

Exit Code	Meaning
0	Success
1	General error
2	Authentication error
3	Not found
4	Validation error

Example Error Handling

#!/bin/bash

if wsm-cli workspace start ws_xyz789; then
  echo "Workspace started successfully"
else
  exit_code=$?
  echo "Failed to start workspace (exit code: $exit_code)"
  exit $exit_code
fi

---

Troubleshooting

Authentication Issues

# Verify configuration
wsm-cli config show

# Re-authenticate
wsm-cli login --force

# Test connection
wsm-cli workspace list

Verbose Logging

Enable verbose logging to debug issues:

wsm-cli --verbose workspace list

Connection Timeouts

If commands are timing out:

# Increase timeout for start/stop operations
wsm-cli workspace start ws_xyz789 --wait --timeout 600

Configuration Issues

If you’re having config issues:

# Check current config
wsm-cli config show

# Use a different config file
wsm-cli --config ~/debug-config.yaml workspace list

# Use a different profile
wsm-cli --profile staging workspace list

---

API Token Management

Creating Tokens

1. Log into your WSM admin dashboard
2. Navigate to your profile page
3. In the API Keys section, click Generate new access key
4. Provide a description and expiration date
5. Copy the token (it will only be shown once)

Using Tokens

Tokens are automatically managed by the login command, but you can also manually add them to your config file:

default:
  baseUrl: https://wsm.example.com
  token: your-api-token-here

Revoking Tokens

1. Log into your WSM admin dashboard
2. Navigate to your profile page
3. In the API Keys section, find the key and click Revoke

---

Best Practices

• Use profiles for different environments (dev, staging, production)
• Store tokens securely - never commit config files to Git
• Use --output json for scripting and automation
• Enable verbose logging when debugging issues
• Use --force carefully - it skips confirmation prompts
• Set up autocomplete for faster command entry
• Keep CLI updated - npm update -g @ordinlabs/wsm-cli

---

Getting Help

Command Help

# General help
wsm-cli --help

# Command-specific help
wsm-cli workspace --help
wsm-cli workspace start --help

Support

• Email: info@ordinlabs.com
• Documentation: Getting Started
• SSH Setup: SSH Configuration

---

Next Steps

• SSH Configuration - Set up SSH access to workspaces
• Getting Started - General setup guide
• Contact Support - Get help with the CLI