Skip to content

Commit daa6ceb

Browse files
stanleykcstanleykc
committed
Documentation for the CLI
Signed-off-by: Kevin Stanley <stanleyk@objectcomputing.com>
1 parent e15c4fc commit daa6ceb

2 files changed

Lines changed: 733 additions & 151 deletions

File tree

‎unityauth-cli/README.md‎

Lines changed: 110 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -6,44 +6,38 @@ Command-line interface for UnityAuth administration.
66

77
The UnityAuth CLI is a cross-platform command-line tool that enables system and tenant administrators to manage users, roles, and permissions in UnityAuth without using the web interface. It's designed for automation, batch operations, and scriptable workflows.
88

9-
## Features
10-
11-
- **User Management**: Create, update, and list users
12-
- **Authentication**: Secure login with OS-native token storage
13-
- **Role & Tenant Discovery**: List available tenants and roles
14-
- **Permission Verification**: Check user permissions for debugging
15-
- **Batch Operations**: Create hundreds of users from CSV files
16-
- **Multiple Output Formats**: Table, JSON, and CSV output
17-
- **Automation-Friendly**: Non-interactive mode for scripts and CI/CD
9+
## Current Status
10+
11+
| Feature | Status |
12+
|---------|--------|
13+
| Authentication (login/logout/token-info) | Implemented |
14+
| User Management (create/list/update roles) | Implemented |
15+
| Tenant Discovery (list/users) | Implemented |
16+
| Role Discovery (list) | Implemented |
17+
| Configuration Management | Implemented |
18+
| Permission Verification | Planned |
19+
| Batch Operations | Planned |
1820

1921
## Installation
2022

2123
### Prerequisites
2224

23-
Before installing the UnityAuth CLI, ensure you have:
24-
2525
- **Python 3.11 or higher**
2626
- **pip** (Python package installer)
2727
- **UnityAuth API endpoint URL**
2828
- **Valid UnityAuth administrator credentials**
2929

3030
#### Verify Python Installation
3131

32-
Check if Python 3.11+ is installed:
33-
3432
```bash
3533
python3 --version
34+
# Should show Python 3.11.x or higher
3635
```
3736

38-
You should see output like `Python 3.11.x` or higher.
39-
4037
#### Install Python (if needed)
4138

42-
If Python is not installed or the version is too old:
43-
4439
**macOS:**
4540
```bash
46-
# Using Homebrew
4741
brew install python@3.11
4842
```
4943

@@ -53,68 +47,28 @@ sudo apt update
5347
sudo apt install python3.11 python3.11-venv python3-pip
5448
```
5549

56-
**RHEL/CentOS/Fedora:**
57-
```bash
58-
sudo dnf install python3.11 python3-pip
59-
```
60-
6150
**Windows:**
62-
Download from [python.org](https://www.python.org/downloads/) and run the installer. Make sure to check "Add Python to PATH" during installation.
63-
64-
#### Verify pip Installation
65-
66-
Check if pip is available:
67-
68-
```bash
69-
python3 -m pip --version
70-
```
71-
72-
If pip is not available, install it:
73-
74-
```bash
75-
# Download get-pip.py
76-
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
51+
Download from [python.org](https://www.python.org/downloads/) and run the installer. Check "Add Python to PATH" during installation.
7752

78-
# Install pip
79-
python3 get-pip.py
80-
81-
# Clean up
82-
rm get-pip.py
83-
```
84-
85-
### Install from PyPI (Production)
86-
87-
Once Python and pip are configured:
53+
### Install from Source (Development)
8854

8955
```bash
90-
python3 -m pip install unityauth-cli
91-
```
92-
93-
### Install for Development
94-
95-
For local development and testing:
56+
cd unityauth-cli
9657

97-
```bash
98-
# Clone the repository (if needed)
99-
cd /path/to/UnityAuth/unityauth-cli
58+
# Create and activate virtual environment
59+
python3 -m venv venv
60+
source venv/bin/activate # On Windows: venv\Scripts\activate
10061

101-
# Install in editable mode with development dependencies
62+
# Install in editable mode
10263
python3 -m pip install -e .
103-
104-
# Or install with dev dependencies
105-
python3 -m pip install -e ".[dev]"
10664
```
10765

10866
### Verify Installation
10967

110-
Confirm the CLI is installed correctly:
111-
11268
```bash
11369
unityauth --version
11470
```
11571

116-
You should see output like `unityauth-cli version 1.0.0`.
117-
11872
## Quick Start
11973

12074
### 1. Configure API Endpoint
@@ -127,14 +81,22 @@ unityauth config set api_url https://auth.example.com
12781

12882
```bash
12983
unityauth login
84+
# Enter email and password when prompted
13085
```
13186

132-
You'll be prompted for your email and password. Your authentication token will be securely stored in your OS credential manager.
87+
Your authentication token is securely stored in your OS credential manager (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux).
13388

134-
### 3. List Tenants
89+
### 3. Explore the System
13590

13691
```bash
92+
# List accessible tenants
13793
unityauth tenant list
94+
95+
# List available roles
96+
unityauth role list
97+
98+
# List users in a tenant
99+
unityauth tenant users 1
138100
```
139101

140102
### 4. Create a User
@@ -149,140 +111,137 @@ unityauth user create \
149111
--role-ids 2,3
150112
```
151113

152-
## Common Commands
153-
154-
### Authentication
114+
## Command Structure
155115

156-
```bash
157-
unityauth login # Login with credentials
158-
unityauth logout # Remove stored token
159-
unityauth token-info # Display current session info
160116
```
161-
162-
### User Management
163-
164-
```bash
165-
unityauth user create ... # Create a new user
166-
unityauth user list --tenant-id 1 # List users in a tenant
167-
unityauth user update USER_ID ... # Update user roles
117+
unityauth
118+
├── login # Authenticate with UnityAuth
119+
├── logout # Remove stored credentials
120+
├── token-info # Display session information
121+
├── config # Configuration management
122+
│ ├── show # Display current config
123+
│ ├── set # Set a config value
124+
│ └── edit # Open config in editor
125+
├── user # User management
126+
│ ├── create # Create a new user
127+
│ ├── list # List users in a tenant
128+
│ └── update # Update user roles
129+
├── tenant # Tenant discovery
130+
│ ├── list # List accessible tenants
131+
│ └── users # List users in a tenant
132+
└── role # Role discovery
133+
└── list # List available roles
168134
```
169135

170-
### Discovery
136+
## Global Options
171137

172-
```bash
173-
unityauth tenant list # List accessible tenants
174-
unityauth role list # List available roles
175-
unityauth permission get ... # Get user permissions
176-
```
138+
All commands support these global options:
177139

178-
### Batch Operations
179-
180-
```bash
181-
unityauth batch create-users users.csv # Create users from CSV
182-
unityauth batch create-users users.csv --dry-run # Preview without creating
183-
```
140+
| Option | Description |
141+
|--------|-------------|
142+
| `--api-url TEXT` | Override API URL from config |
143+
| `--format [table\|json\|csv]` | Output format (default: table) |
144+
| `--verbose` | Enable debug output |
145+
| `--version` | Show version and exit |
146+
| `--help` | Show help message |
184147

185148
## Output Formats
186149

187-
The CLI supports three output formats:
150+
```bash
151+
# Human-readable table (default)
152+
unityauth tenant list
188153

189-
- **table** (default): Human-readable ASCII tables
190-
- **json**: Machine-readable JSON for scripting
191-
- **csv**: Spreadsheet-compatible CSV
154+
# Machine-readable JSON
155+
unityauth tenant list --format json
192156

193-
Example:
157+
# Spreadsheet-compatible CSV
158+
unityauth tenant list --format csv
194159

195-
```bash
160+
# Pipe JSON to jq for processing
196161
unityauth tenant list --format json | jq '.[0].name'
197162
```
198163

199-
## Automation
200-
201-
### Non-Interactive Mode
164+
## Environment Variables
202165

203-
Provide all parameters via command-line options:
166+
| Variable | Description |
167+
|----------|-------------|
168+
| `UNITYAUTH_API_URL` | API endpoint URL |
169+
| `UNITYAUTH_EMAIL` | Login email address |
170+
| `UNITYAUTH_PASSWORD` | Login password (for non-interactive mode) |
204171

172+
Example:
205173
```bash
206-
unityauth login --email admin@example.com --password "$ADMIN_PASSWORD"
174+
export UNITYAUTH_API_URL="https://auth.example.com"
175+
unityauth login --email admin@example.com
207176
```
208177

209-
### Environment Variables
178+
## Exit Codes
210179

211-
```bash
212-
export UNITYAUTH_API_URL="https://auth.example.com"
213-
export UNITYAUTH_EMAIL="admin@example.com"
214-
export UNITYAUTH_PASSWORD="secret"
180+
| Code | Meaning |
181+
|------|---------|
182+
| 0 | Success |
183+
| 1 | General error (validation, network, API) |
184+
| 2 | Authentication error |
185+
| 3 | Permission/authorization error |
186+
| 4 | Configuration error |
215187

216-
unityauth login
217-
```
188+
## Configuration
218189

219-
### Exit Codes
190+
Configuration is stored in `~/.config/unityauth-cli/config.yml`:
220191

221-
- `0`: Success
222-
- `1`: General error (validation, network, API)
223-
- `2`: Authentication error
224-
- `3`: Permission error
225-
- `4`: Configuration error
192+
```yaml
193+
api_url: https://auth.example.com
194+
default_format: table
195+
timeout: 30
196+
```
197+
198+
Manage configuration:
199+
```bash
200+
unityauth config show # View current settings
201+
unityauth config set api_url URL # Set API endpoint
202+
unityauth config set timeout 60 # Set request timeout
203+
unityauth config edit # Open in editor
204+
```
226205

227206
## Documentation
228207

229-
- [Quickstart Guide](../specs/001-unityauth-cli/quickstart.md) - Detailed usage examples
230-
- [API Endpoints](../CLAUDE.md) - UnityAuth API reference
231-
- [Project README](../README.md) - Main UnityAuth documentation
208+
- [User Guide](docs/user-guide.md) - Complete command reference
209+
- [Quickstart Guide](../specs/001-unityauth-cli/quickstart.md) - Detailed usage scenarios
210+
- [UnityAuth API](../CLAUDE.md) - Backend API reference
232211

233212
## Development
234213

235-
### Setting Up Development Environment
214+
### Setup
236215

237216
```bash
238-
# Navigate to the CLI directory
239217
cd unityauth-cli
240-
241-
# Install development dependencies
242-
python3 -m pip install -r requirements-dev.txt
243-
244-
# Or install in editable mode with dev extras
218+
python3 -m venv venv
219+
source venv/bin/activate
245220
python3 -m pip install -e ".[dev]"
246221
```
247222

248223
### Running Tests
249224

250225
```bash
251-
# Run unit tests
252226
pytest tests/unit/
253-
254-
# Run integration tests
255-
pytest tests/integration/
256-
257-
# Run all tests with coverage
258227
pytest --cov=unityauth_cli
259228
```
260229

261230
### Code Quality
262231

263232
```bash
264-
# Format code
265-
black src/
266-
267-
# Lint code
268-
flake8 src/
269-
270-
# Type checking
271-
mypy src/
233+
black src/ # Format code
234+
flake8 src/ # Lint
235+
mypy src/ # Type checking
272236
```
273237

274238
## Security
275239

276-
- **Token Storage**: JWT tokens are encrypted at rest using OS-native credential stores (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux)
277-
- **HTTPS Required**: API communication requires HTTPS
278-
- **No Password Storage**: Passwords are never stored; only JWT tokens
279-
- **Secure CSV Handling**: CSV files containing passwords should be deleted after batch operations
280-
281-
## Support
282-
283-
- **GitHub Issues**: https://github.com/UnityFoundation-io/UnityAuth/issues
284-
- **Documentation**: See [CLAUDE.md](../CLAUDE.md) for UnityAuth architecture
240+
- **Token Storage**: JWT tokens encrypted using OS-native credential stores
241+
- **HTTPS Required**: All API communication uses HTTPS
242+
- **No Password Storage**: Only JWT tokens are persisted, never passwords
243+
- **Secure Prompts**: Password input is hidden when typing
285244

286245
## License
287246

288-
MIT License - See LICENSE file for details
247+
MIT License - See LICENSE file for details.

0 commit comments

Comments
 (0)