Workspaces

# Hierarchical breakdown of a workspace and its resources
Workspace
├── Settings
│   ├── Name
│   ├── Slug (URL-safe identifier)
│   └── Billing info
│
├── Members
│   ├── Owners (full control)
│   ├── Admins (manage machines, users)
│   ├── Members (access sessions)
│   └── Guests (read-only, optional)
│
├── Machines
│   ├── web-1 (hostname)
│   ├── web-2
│   └── db-1
│
├── Sessions
│   ├── Active sessions
│   └── Session history
│
└── API Keys
    ├── Personal keys (per user)
    └── Workspace keys (shared)

# Create a new workspace with a URL-safe slug
cmdop workspace create "My Workspace" --slug my-workspace
 
# Set the active workspace for subsequent CLI commands
cmdop workspace use my-workspace
 
# Show all workspaces you belong to
cmdop workspace list

# Send an invitation email with assigned role to a new team member
await client.workspace.invite(
    email="[email protected]",
    role="member"
)

# Hostnames must be unique per workspace; duplicates are rejected
Workspace: "acme-corp"
├── web-1  ✅ (unique)
├── web-2  ✅ (unique)
└── web-1  ❌ (duplicate, rejected)

# Different workspaces can reuse the same hostname
Workspace: "globex"
├── web-1  ✅ (unique in this workspace)

# Generate a personal API key named "my-laptop" for the current workspace
cmdop auth create-key --name "my-laptop"
 
# Key format: cmd_<workspace>_<random>
# Example: cmd_acme_a1b2c3d4e5f6...

# Generate a shared workspace-level key (requires admin role)
cmdop auth create-key --workspace --name "ci-cd"

# The API key determines which workspace the client can access
client = AsyncCMDOPClient.remote(api_key="cmd_acme_xxx")
 
# Success: web-1 exists in the acme workspace
session = await client.terminal.get_active_session("web-1")
 
# Error: globex-server is not in the acme workspace — access denied
session = await client.terminal.get_active_session("globex-server")

# List all workspaces your account belongs to
cmdop workspace list
 
# Change the active workspace for CLI commands
cmdop workspace use my-workspace
 
# Display the currently active workspace
cmdop workspace current

# In the SDK, the API key determines the workspace automatically
# To switch workspaces, instantiate a client with a different key
 
acme_client = AsyncCMDOPClient.remote(api_key="cmd_acme_xxx")
globex_client = AsyncCMDOPClient.remote(api_key="cmd_globex_yyy")

# Separate workspaces by environment for clear isolation
Company Structure:
├── acme-production    # Prod servers
├── acme-staging       # Staging environment
└── acme-development   # Dev machines

Each team/environment gets isolated workspace.

# Assign roles matching each person's responsibility level
Production Workspace:
├── Owners: [email protected]
├── Admins: senior-devs
├── Members: all developers
└── Guests: auditors (read-only)

# Keep personal and automation keys separate for easy revocation
Personal keys: cmd_acme_alice_xxx
CI/CD keys:    cmd_acme_cicd_xxx

Revoke personal key if laptop stolen.
CI key stays active.

# Review who has access to the workspace
cmdop workspace members
 
# List all API keys (check for unused or stale keys)
cmdop auth list-keys
 
# View audit trail for the last 30 days
cmdop audit list --days 30

# A single user account can have different roles in different workspaces
[email protected]
├── Member of: acme-production
├── Admin of: acme-staging
└── Owner of: alice-personal

# Alice can switch between workspaces
# Different permissions in each

# Permanently delete a workspace and all its data (owner only)
cmdop workspace delete my-workspace --confirm
 
# This deletes:
# - All machines
# - All sessions
# - All API keys
# - All audit logs
# - Member associations (not user accounts)