User Commands
Overview
User management commands provide comprehensive user administration capabilities including user creation, listing, detailed information retrieval, and removal. These commands integrate with SSH key management and repository access control for complete user lifecycle management.
Table of Contents
cpm user add
Description
Add a new user to the cpm system with optional email and SSH public key. Users can be granted repository access and organization membership after creation.
Syntax
cpm user add <username> [flags]
Arguments
| Argument | Required | Description |
|---|---|---|
username |
Yes | Unique username (alphanumeric with hyphens/underscores) |
Flags
| Flag | Type | Description |
|---|---|---|
--email <address> |
string | User email address |
--key <public-key> |
string | SSH public key (ed25519 or RSA) |
--key-file <path> |
string | Path to SSH public key file |
Behavior
- Validates username uniqueness
- Validates email format if provided
- Validates SSH public key format if provided
- Creates user record in database
- Stores SSH key if provided
- Generates user ID
- Sets creation timestamp
Examples
Basic User Creation
cpm user add alice
# Output:
# User 'alice' created successfully
# ID: 1
# Created: 2024-01-15 10:30:00
User with Email
cpm user add bob --email bob@example.com
# Output:
# User 'bob' created successfully
# ID: 2
# Email: bob@example.com
# Created: 2024-01-15 10:35:00
User with SSH Key
cpm user add charlie --email charlie@example.com \
--key "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl charlie@laptop"
# Output:
# User 'charlie' created successfully
# ID: 3
# Email: charlie@example.com
# SSH Key: ed25519 (fingerprint: SHA256:abc123...)
# Created: 2024-01-15 10:40:00
User with Key File
cpm user add david --email david@example.com --key-file ~/.ssh/id_ed25519.pub
# Output:
# Reading public key from: /home/user/.ssh/id_ed25519.pub
# User 'david' created successfully
# ID: 4
# Email: david@example.com
# SSH Key: ed25519 (fingerprint: SHA256:def456...)
# Created: 2024-01-15 10:45:00
SSH Key Validation
cpm validates SSH public keys:
# Valid key types
- ssh-ed25519 (recommended)
- ssh-rsa
- ecdsa-sha2-nistp256
- ecdsa-sha2-nistp384
- ecdsa-sha2-nistp521
# Key format
<type> <key-data> <comment>
# Example
ssh-ed25519 AAAAC3Nz...GKJl user@host
Database Effects
Creates record in users table:
INSERT INTO users (username, email, public_key, created_at)
VALUES ('alice', 'alice@example.com', 'ssh-ed25519 AAAA...', CURRENT_TIMESTAMP);
Common Errors
| Error | Cause | Solution |
|---|---|---|
username already exists |
Username collision | Choose different username |
invalid email format |
Email not valid | Use proper email format |
invalid SSH key |
Key format incorrect | Verify key with ssh-keygen -l |
key file not found |
File doesn't exist | Check file path |
invalid username |
Contains invalid chars | Use alphanumeric, hyphens, underscores |
cpm user list
Description
List all users in the system with their details in a formatted table. Provides overview of user base with key information.
Syntax
cpm user list [flags]
Flags
| Flag | Type | Description |
|---|---|---|
--format <type> |
string | Output format: table (default), json, yaml, csv |
--sort <field> |
string | Sort by: username, email, created |
--filter <pattern> |
string | Filter by username pattern |
Examples
Basic List
cpm user list
# Output:
# USERS
#
# ID Username Email SSH Key Created
# -- --------- ------------------ ------- -------------------
# 1 alice alice@example.com Yes 2024-01-15 10:30:00
# 2 bob bob@example.com Yes 2024-01-15 10:35:00
# 3 charlie charlie@example.com Yes 2024-01-15 10:40:00
# 4 david david@example.com Yes 2024-01-15 10:45:00
# 5 eve eve@example.com No 2024-01-16 09:00:00
#
# Total: 5 users
JSON Output
cpm user list --format json
# Output:
# [
# {
# "id": 1,
# "username": "alice",
# "email": "alice@example.com",
# "has_ssh_key": true,
# "created_at": "2024-01-15T10:30:00Z"
# },
# {
# "id": 2,
# "username": "bob",
# "email": "bob@example.com",
# "has_ssh_key": true,
# "created_at": "2024-01-15T10:35:00Z"
# }
# ]
Filtered List
cpm user list --filter "al*"
# Output:
# USERS (filtered by 'al*')
#
# ID Username Email SSH Key Created
# -- --------- ------------------ ------- -------------------
# 1 alice alice@example.com Yes 2024-01-15 10:30:00
#
# Total: 1 user
Sorted List
cpm user list --sort email
# Output: Users sorted by email address
cpm user show
Description
Display detailed information about a specific user including SSH key details, organization memberships, and repository access permissions.
Syntax
cpm user show <username>
Arguments
| Argument | Required | Description |
|---|---|---|
username |
Yes | Username to display |
Examples
cpm user show alice
# Output:
# USER DETAILS
#
# Username: alice
# ID: 1
# Email: alice@example.com
# Created: 2024-01-15 10:30:00
#
# SSH PUBLIC KEY
# Type: ed25519
# Fingerprint: SHA256:abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
# Key: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl alice@laptop
#
# ORGANIZATION MEMBERSHIPS
#
# Organization Role Joined
# ------------- ------ -------------------
# engineering admin 2024-01-15 11:00:00
# devops member 2024-01-16 09:30:00
#
# REPOSITORY ACCESS
#
# Repository Organization Access Level Granted
# ------------ ------------ ------------ -------------------
# webapp engineering write 2024-01-15 12:00:00
# api-server engineering write 2024-01-16 08:30:00
# infra-tools devops read 2024-01-16 09:45:00
#
# Total: 2 organizations, 3 repositories
User Without SSH Key
cpm user show eve
# Output:
# USER DETAILS
#
# Username: eve
# ID: 5
# Email: eve@example.com
# Created: 2024-01-16 09:00:00
#
# SSH PUBLIC KEY
# No SSH key configured
#
# ORGANIZATION MEMBERSHIPS
# No organization memberships
#
# REPOSITORY ACCESS
# No repository access configured
cpm user remove
Description
Remove a user from the system. This is a destructive operation that requires confirmation. Removes all organization memberships and repository access permissions.
Syntax
cpm user remove <username>
Arguments
| Argument | Required | Description |
|---|---|---|
username |
Yes | Username to remove |
Behavior
- Prompts for confirmation
- Removes all organization memberships
- Revokes all repository access
- Deletes SSH key associations
- Deletes user record from database
- Cannot be undone
Examples
cpm user remove alice
# Prompt:
# WARNING: This will permanently delete user 'alice'
# - All organization memberships will be removed
# - All repository access will be revoked
# - User SSH key associations will be deleted
# - This action cannot be undone
#
# Type the username to confirm: alice
# Output:
# Removing user 'alice' from 2 organizations...
# Revoking access to 3 repositories...
# Deleting SSH key associations...
# Deleting user record...
#
# User 'alice' successfully removed
Force Remove (skip confirmation)
cpm user remove bob --force
# Output:
# User 'bob' removed (forced)
Common Errors
| Error | Cause | Solution |
|---|---|---|
user not found |
Username doesn't exist | Check username with cpm user list |
confirmation mismatch |
Typed name doesn't match | Type exact username |
User Management Workflows
Onboarding New User
# Create user account
cpm user add alice --email alice@example.com --key-file ~/.ssh/alice_id_ed25519.pub
# Add to organization
cpm org add-member engineering alice --role member
# Grant repository access (if needed beyond org access)
# This is typically handled by organization membership
# Verify setup
cpm user show alice
Bulk User Creation
# Using a script for multiple users
for user in alice bob charlie david; do
cpm user add $user --email $user@example.com
done
# Add all to organization
for user in alice bob charlie david; do
cpm org add-member engineering $user
done
User Audit
# List all users
cpm user list
# Check specific user details
cpm user show alice
# Export user list
cpm user list --format json > users_export.json
# Filter users without SSH keys
cpm user list --format json | jq '.[] | select(.has_ssh_key == false)'
Offboarding User
# Review user access
cpm user show departing-user
# Remove from organizations (optional, done automatically)
cpm org remove-member engineering departing-user
cpm org remove-member devops departing-user
# Remove user account (includes all access)
cpm user remove departing-user
# Verify removal
cpm user list | grep departing-user
# (should return no results)
Update User Information
# Remove user
cpm user remove alice
# Re-add with updated information
cpm user add alice --email alice-new@example.com --key-file ~/.ssh/alice_new.pub
# Restore organization memberships
cpm org add-member engineering alice --role admin
SSH Key Management
# Add user without key initially
cpm user add newuser --email newuser@example.com
# User generates key and provides public key
cpm user remove newuser
cpm user add newuser --email newuser@example.com --key "ssh-ed25519 AAAA..."
# Verify key
cpm user show newuser
Integration with Other Commands
With Organization Commands
# Create user and immediately add to org
cpm user add alice --email alice@example.com
cpm org add-member engineering alice --role admin
# Show user's org memberships
cpm user show alice
cpm org show engineering
With Repository Commands
# Repository access is typically granted through organizations
cpm user add alice --email alice@example.com
cpm org add-member engineering alice
cpm org add-repo engineering myproject
# Alice now has access to myproject through engineering org
With SSH Key Commands
# User management integrates with SSH key system
cpm user add alice --email alice@example.com --key-file ~/.ssh/id_ed25519.pub
# The key is stored in user record and can be used for:
# - Server authentication
# - Repository access
# - Key deployment
Best Practices
Username Conventions
- Use lowercase letters and hyphens
- Match corporate email prefix: alice, bob-smith
- Keep consistent across systems
- Avoid special characters
Email Management
- Always include email for audit trail
- Use corporate email addresses
- Verify email addresses before adding
- Document email change procedures
SSH Key Management
- Always add SSH keys during user creation
- Use ed25519 keys (recommended)
- Regularly rotate keys
- Remove keys for departing users
- Never share private keys
Access Control
- Grant minimum necessary permissions
- Use organization-based access primarily
- Regular access audits
- Document access requirements
- Remove access promptly when no longer needed
User Lifecycle
- Onboarding: Create user, add email, add SSH key, assign to orgs
- Active: Regular access reviews, permission updates
- Offboarding: Remove from orgs first, then remove user account
- Audit: Regular user list reviews, inactive user cleanup