<div align="center">
<a href="https://systemprompt.io">
<img src="https://systemprompt.io/logo.svg" alt="systemprompt.io" width="150" />
</a>
<p><strong>Production infrastructure for AI agents</strong></p>
<p><a href="https://systemprompt.io">systemprompt.io</a> • <a href="https://systemprompt.io/documentation">Documentation</a> • <a href="https://github.com/systempromptio/systemprompt-core">Core</a> • <a href="https://github.com/systempromptio/systemprompt-template">Template</a></p>
</div>
---
# Users CLI Commands
This document provides complete documentation for AI agents to use the users CLI commands. All commands support non-interactive mode for automation.
**Important:** All user identifier arguments (`<USER>`) accept:
- Username (e.g., `johndoe`)
- UUID (e.g., `a602013b-f059-47eb-9169-df6e8f1372d4`)
- Email (e.g., `john@example.com`)
---
## Prerequisites
```bash
export SYSTEMPROMPT_PROFILE=/var/www/html/tyingshoelaces/.systemprompt/profiles/local/profile.yaml
cd /var/www/html/systemprompt-core
cargo build --package systemprompt-cli
alias sp="./target/debug/systemprompt --non-interactive"
```
---
## Command Reference
| `admin users list` | List users with pagination | No |
| `admin users show <USER>` | Show detailed user information | No |
| `admin users search <QUERY>` | Search users by name/email | No |
| `admin users create` | Create a new user | No |
| `admin users update <USER>` | Update user fields | No |
| `admin users delete <USER>` | Delete a user | **Yes** |
| `admin users count` | Get total user count | No |
| `admin users export` | Export users to JSON | No |
| `admin users stats` | Show user statistics dashboard | No |
| `admin users merge` | Merge source user into target | **Yes** |
| `admin users bulk delete` | Bulk delete users by filter | **Yes** |
| `admin users bulk update` | Bulk update user status | **Yes** |
| `admin users role assign <USER>` | Assign roles to user | No |
| `admin users role promote <USER>` | Promote user to admin | No |
| `admin users role demote <USER>` | Demote user from admin | No |
| `admin users session list <USER>` | List user sessions | No |
| `admin users session end` | End user session(s) | **Yes** |
| `admin users session cleanup` | Clean up old anonymous users | **Yes** |
| `admin users ban list` | List active IP bans | No |
| `admin users ban add <IP>` | Ban IP address | No |
| `admin users ban remove <IP>` | Remove IP ban | **Yes** |
| `admin users ban check <IP>` | Check if IP is banned | No |
| `admin users ban cleanup` | Clean up expired bans | **Yes** |
---
## Core Commands
### users list
List all users with pagination and filtering.
```bash
sp admin users list
sp --json users list
sp admin users list --limit 50 --offset 0
sp admin users list --role admin
sp admin users list --status active
```
**Flags:**
| `--limit` | `20` | Maximum number of results |
| `--offset` | `0` | Number of results to skip |
| `--role` | None | Filter by role: `admin`, `user`, `anonymous` |
| `--status` | None | Filter by status: `active`, `inactive`, `suspended`, `pending`, `deleted`, `temporary` |
**Output Structure:**
```json
{
"users": [
{
"id": "a602013b-f059-47eb-9169-df6e8f1372d4",
"name": "johndoe",
"email": "john@example.com",
"status": "active",
"roles": ["user"],
"created_at": "2024-01-15T10:30:00Z"
}
],
"total": 1,
"limit": 20,
"offset": 0
}
```
---
### users show
Display detailed information for a specific user.
```bash
sp admin users show johndoe
sp admin users show john@example.com
sp admin users show a602013b-f059-47eb-9169-df6e8f1372d4
sp --json users show johndoe
sp admin users show johndoe --sessions
sp admin users show johndoe --activity
```
**Arguments:**
| `<USER>` | Yes | Username, email, or UUID |
**Flags:**
| `--sessions` | `false` | Include user sessions |
| `--activity` | `false` | Include activity statistics |
**Output Structure:**
```json
{
"id": "a602013b-f059-47eb-9169-df6e8f1372d4",
"name": "johndoe",
"email": "john@example.com",
"full_name": "John Doe",
"display_name": "John",
"status": "active",
"email_verified": false,
"roles": ["user"],
"is_bot": false,
"is_scanner": false,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"sessions": [...],
"activity": {...}
}
```
---
### users search
Search users by name, email, or full name.
```bash
sp admin users search "john"
sp --json users search "john"
sp admin users search "example.com" --limit 10
```
**Arguments:**
| `<QUERY>` | Yes | Search query (substring match) |
**Flags:**
| `--limit` | `20` | Maximum number of results |
**Output Structure:**
```json
{
"users": [
{
"id": "a602013b-f059-47eb-9169-df6e8f1372d4",
"name": "johndoe",
"email": "john@example.com",
"status": "active",
"roles": ["user"],
"created_at": "2024-01-15T10:30:00Z"
}
],
"total": 1,
"limit": 20,
"offset": 0
}
```
---
### users create
Create a new user.
```bash
sp admin users create --name "johndoe" --email "john@example.com"
sp admin users create --name "johndoe" --email "john@example.com" --full-name "John Doe" --display-name "John"
```
**Required Flags:**
| `--name` | Yes | Username (unique) |
| `--email` | Yes | Email address (unique) |
**Optional Flags:**
| `--full-name` | None | Full name |
| `--display-name` | None | Display name |
**Output Structure:**
```json
{
"id": "a602013b-f059-47eb-9169-df6e8f1372d4",
"name": "johndoe",
"email": "john@example.com",
"message": "User 'johndoe' created successfully"
}
```
---
### users update
Update user fields. Accepts username, email, or UUID.
```bash
sp admin users update johndoe --email "newemail@example.com"
sp admin users update johndoe --full-name "John Smith" --display-name "Johnny"
sp admin users update johndoe --status suspended
sp admin users update a602013b-f059-47eb-9169-df6e8f1372d4 --email-verified true
```
**Arguments:**
| `<USER>` | Yes | Username, email, or UUID |
**Modification Flags (at least one required):**
| `--email` | Update email address |
| `--full-name` | Update full name |
| `--display-name` | Update display name |
| `--status` | Update status: `active`, `inactive`, `suspended` |
| `--email-verified` | Set email verification status |
**Output Structure:**
```json
{
"id": "a602013b-f059-47eb-9169-df6e8f1372d4",
"name": "johndoe",
"email": "newemail@example.com",
"message": "User 'johndoe' updated successfully"
}
```
---
### users delete
Delete a user permanently. Requires `--yes` flag.
```bash
sp admin users delete johndoe --yes
sp admin users delete john@example.com --yes
sp admin users delete a602013b-f059-47eb-9169-df6e8f1372d4 --yes
```
**Arguments:**
| `<USER>` | Yes | Username, email, or UUID |
**Required Flags:**
| `--yes` / `-y` | Yes | Confirm deletion |
**Output Structure:**
```json
{
"id": "a602013b-f059-47eb-9169-df6e8f1372d4",
"message": "User 'johndoe' deleted successfully"
}
```
---
### users count
Get total user count.
```bash
sp admin users count
sp --json users count
```
**Output Structure:**
```json
{
"count": 150
}
```
---
## Role Management Commands
### users role assign
Assign roles to a user. Accepts username, email, or UUID.
```bash
sp admin users role assign johndoe --roles admin,user
sp admin users role assign john@example.com --roles admin
sp admin users role assign a602013b-f059-47eb-9169-df6e8f1372d4 --roles user
```
**Arguments:**
| `<USER>` | Yes | Username, email, or UUID |
**Required Flags:**
| `--roles` | Yes | Comma-separated roles: `admin`, `user`, `anonymous` |
**Output Structure:**
```json
{
"id": "a602013b-f059-47eb-9169-df6e8f1372d4",
"name": "johndoe",
"roles": ["admin", "user"],
"message": "Roles assigned to user 'johndoe'"
}
```
---
### users role promote
Promote a user to admin. Accepts username, email, or UUID.
```bash
sp admin users role promote johndoe
sp admin users role promote john@example.com
```
**Arguments:**
| `<USER>` | Yes | Username, email, or UUID |
**Output Structure:**
```json
{
"id": "a602013b-f059-47eb-9169-df6e8f1372d4",
"name": "johndoe",
"roles": ["user", "admin"],
"message": "User 'johndoe' promoted to admin"
}
```
---
### users role demote
Demote a user from admin. Accepts username, email, or UUID.
```bash
sp admin users role demote johndoe
sp admin users role demote john@example.com
```
**Arguments:**
| `<USER>` | Yes | Username, email, or UUID |
**Output Structure:**
```json
{
"id": "a602013b-f059-47eb-9169-df6e8f1372d4",
"name": "johndoe",
"roles": ["user"],
"message": "User 'johndoe' demoted from admin"
}
```
---
## Session Management Commands
### users session list
List sessions for a specific user. Accepts username, email, or UUID.
```bash
sp admin users session list johndoe
sp --json users session list johndoe
sp admin users session list johndoe --active
sp admin users session list johndoe --limit 10
```
**Arguments:**
| `<USER>` | Yes | Username, email, or UUID |
**Flags:**
| `--active` | `false` | Show only active sessions |
| `--limit` | `20` | Maximum number of results |
**Output Structure:**
```json
{
"sessions": [
{
"session_id": "sess_4460f4d4-57ab-4996-a70a-5b6c086e4ae5",
"ip_address": "192.168.1.1",
"user_agent": "Mozilla/5.0...",
"device_type": "desktop",
"started_at": "2024-01-15T10:30:00Z",
"last_activity_at": "2024-01-15T11:45:00Z",
"is_active": true
}
],
"total": 1
}
```
---
### users session end
End a user session. Requires `--yes` flag.
```bash
# End specific session
sp admin users session end sess_4460f4d4-57ab-4996-a70a-5b6c086e4ae5 --yes
# End all sessions for a user
sp admin users session end --user johndoe --all --yes
sp admin users session end --user john@example.com --all --yes
```
**Arguments:**
| `<SESSION_ID>` | Yes* | Session ID to end (*unless using `--all`) |
**Flags:**
| `--yes` / `-y` | Yes | Confirm action |
| `--user` | No | User identifier (required with `--all`) |
| `--all` | No | End all sessions for user |
**Output Structure:**
```json
{
"ended": ["sess_4460f4d4-57ab-4996-a70a-5b6c086e4ae5"],
"count": 1,
"message": "Session(s) ended successfully"
}
```
---
### users session cleanup
Clean up old anonymous users. Requires `--yes` flag.
```bash
sp admin users session cleanup --days 30 --yes
```
**Required Flags:**
| `--days` | Yes | Delete anonymous users older than N days |
| `--yes` / `-y` | Yes | Confirm action |
**Output Structure:**
```json
{
"cleaned": 15,
"message": "Cleaned up 15 old anonymous user(s)"
}
```
---
## IP Ban Management Commands
### users ban list
List active IP bans.
```bash
sp admin users ban list
sp --json users ban list
sp admin users ban list --limit 50
```
**Flags:**
| `--limit` | `100` | Maximum number of results |
**Output Structure:**
```json
{
"bans": [
{
"ip_address": "192.168.1.100",
"reason": "Suspicious activity",
"banned_at": "2024-01-15T10:30:00Z",
"expires_at": "2024-01-22T10:30:00Z",
"is_permanent": false,
"ban_count": 1,
"ban_source": "cli"
}
],
"total": 1
}
```
---
### users ban add
Ban an IP address.
```bash
sp admin users ban add 192.168.1.100 --reason "Suspicious activity"
sp admin users ban add 192.168.1.100 --reason "Abuse" --duration 7d
sp admin users ban add 192.168.1.100 --reason "Permanent ban" --permanent
```
**Arguments:**
| `<IP>` | Yes | IP address to ban |
**Required Flags:**
| `--reason` | Yes | Reason for ban |
**Optional Flags:**
| `--duration` | `7d` | Ban duration (e.g., `1h`, `7d`, `30d`) |
| `--permanent` | `false` | Make ban permanent |
**Output Structure:**
```json
{
"ip_address": "192.168.1.100",
"reason": "Suspicious activity",
"expires_at": "2024-01-22T10:30:00Z",
"is_permanent": false,
"message": "IP address '192.168.1.100' has been banned"
}
```
---
### users ban remove
Remove an IP ban. Requires `--yes` flag.
```bash
sp admin users ban remove 192.168.1.100 --yes
```
**Arguments:**
| `<IP>` | Yes | IP address to unban |
**Required Flags:**
| `--yes` / `-y` | Yes | Confirm action |
**Output Structure:**
```json
{
"ip_address": "192.168.1.100",
"removed": true,
"message": "IP address '192.168.1.100' has been unbanned"
}
```
---
### users ban check
Check if an IP address is banned.
```bash
sp admin users ban check 192.168.1.100
sp --json users ban check 192.168.1.100
```
**Arguments:**
| `<IP>` | Yes | IP address to check |
**Output Structure:**
```json
{
"ip_address": "192.168.1.100",
"is_banned": true,
"ban_info": {
"ip_address": "192.168.1.100",
"reason": "Suspicious activity",
"banned_at": "2024-01-15T10:30:00Z",
"expires_at": "2024-01-22T10:30:00Z",
"is_permanent": false,
"ban_count": 1,
"ban_source": "cli"
}
}
```
---
### users ban cleanup
Clean up expired bans. Requires `--yes` flag.
```bash
sp admin users ban cleanup --yes
```
**Required Flags:**
| `--yes` / `-y` | Yes | Confirm action |
**Output Structure:**
```json
{
"cleaned": 5,
"message": "Cleaned up 5 expired ban(s)"
}
```
---
## Complete User Management Flow Example
This flow demonstrates the full user lifecycle:
```bash
# Phase 1: List existing users
sp --json users list
sp --json users count
# Phase 2: Create new user
sp admin users create --name "newuser" --email "new@example.com" --full-name "New User"
# Phase 3: Verify creation
sp --json users show newuser
sp --json users search "newuser"
# Phase 4: Update user
sp admin users update newuser --display-name "Newbie"
# Phase 5: Promote to admin
sp admin users role promote newuser
# Phase 6: Verify role
sp --json users show newuser
# Should show roles: ["user", "admin"]
# Phase 7: Demote from admin
sp admin users role demote newuser
# Phase 8: Check sessions
sp --json users session list newuser
# Phase 9: Delete user
sp admin users delete newuser --yes
# Phase 10: Verify deletion
sp --json users list
```
---
## Session and Security Flow Example
```bash
# Check for active sessions
sp --json users session list johndoe --active
# End specific session
sp admin users session end sess_suspicious123 --yes
# End all sessions for a user
sp admin users session end --user johndoe --all --yes
# Ban suspicious IP
sp admin users ban add 10.0.0.100 --reason "Multiple failed login attempts"
# Check ban status
sp --json users ban check 10.0.0.100
# List all bans
sp --json users ban list
# Remove ban after investigation
sp admin users ban remove 10.0.0.100 --yes
# Cleanup expired bans
sp admin users ban cleanup --yes
```
---
## Error Handling
### Missing Required Flags
```bash
sp admin users create --name test
# Error: --email is required
sp admin users delete johndoe
# Error: --yes is required to delete users in non-interactive mode
sp admin users role assign johndoe
# Error: At least one role must be specified
sp admin users ban add 10.0.0.1
# Error: --reason is required
```
### Not Found Errors
```bash
sp admin users show nonexistent
# Error: User 'nonexistent' not found
sp admin users role promote nonexistent
# Error: User 'nonexistent' not found
```
### Duplicate Errors
```bash
sp admin users create --name "existing" --email "existing@example.com"
# Error: User with email 'existing@example.com' already exists
```
---
## JSON Output
All commands support `--json` flag for structured output:
```bash
# Verify JSON is valid
# Extract specific fields
sp --json users count | jq '.count'
# Filter by criteria
sp --json users session list johndoe | jq '.sessions[] | select(.is_active == true)'
```
---
## Compliance Checklist
- [x] All `execute` functions accept `config: &CliConfig`
- [x] All destructive commands require `--yes` / `-y` flag
- [x] All output types derive `Serialize`, `Deserialize`
- [x] No `println!` / `eprintln!` - uses `CliService`
- [x] No `unwrap()` / `expect()` - uses `?` with proper error handling
- [x] JSON output supported via `--json` flag
- [x] Proper error messages for missing required flags
- [x] All user identifiers accept username, email, or UUID
---
## License
Business Source License 1.1 - See [LICENSE](https://github.com/systempromptio/systemprompt-core/blob/main/LICENSE) for details.