Skip to content

Commit 3b12c17

Browse files
amrit110amrit110
authored
Merge pull request #55 from VectorInstitute/update_docs_cli
Update docs cli
2 parents 41b413b + 443af9b commit 3b12c17

File tree

5 files changed

+148
-428
lines changed

5 files changed

+148
-428
lines changed

‎docs/cli.md‎

Lines changed: 144 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,122 @@
11
# CLI Reference
22

3-
The `aieng-platform-onboard` package provides a command-line tool for bootcamp participant onboarding, authentication, environment setup, and admin operations.
3+
The `aieng-platform-onboard` package provides command-line tools for bootcamp participant onboarding, authentication, and administration.
44

55
## Installation
66

77
```bash
88
pip install aieng-platform-onboard
99
```
1010

11-
## Commands
11+
## Overview
1212

13-
### `onboard`
13+
The CLI provides two main commands:
1414

15-
Main command for onboarding bootcamp participants with team-specific API keys.
15+
- **`onboard`** - Participant onboarding with team-specific API keys
16+
- **`onboard admin`** - Admin commands for managing participants and teams
1617

17-
### `onboard admin`
18+
---
1819

19-
Admin commands for managing participants and teams.
20+
## Participant Onboarding
2021

21-
#### Usage
22+
Main command for onboarding bootcamp participants with team-specific API keys.
23+
24+
### Usage
2225

2326
```bash
2427
onboard [OPTIONS]
2528
```
2629

27-
#### Participant Onboarding
30+
### Options
31+
32+
#### Required
33+
34+
| Option | Description | Example |
35+
|--------|-------------|---------|
36+
| `--bootcamp-name` | Name of the bootcamp | `--bootcamp-name fall-2025` |
37+
| `--test-script` | Path to integration test script | `--test-script tests/integration/test_api_keys.py` |
38+
39+
#### Optional
40+
41+
| Option | Description | Default |
42+
|--------|-------------|---------|
43+
| `--gcp-project` | GCP project ID | `coderd` |
44+
| `--output-dir` | Directory for .env file | `.` (current directory) |
45+
| `--firebase-api-key` | Firebase Web API key for token exchange | (from `FIREBASE_WEB_API_KEY` env var) |
46+
| `--skip-test` | Skip integration tests | `False` |
47+
| `--force` | Force re-onboarding even if already onboarded | `False` |
48+
| `--admin-status-report` | Display onboarding status for all participants (admin only) | `False` |
49+
| `--version` | Show version number and exit | - |
50+
51+
### Onboarding Process
2852

29-
Standard onboarding flow for bootcamp participants:
53+
The participant onboarding flow consists of 9 steps:
3054

55+
1. **Identify Participant** - Detects GitHub username from environment
56+
2. **Fetch Authentication Token** - Retrieves fresh token from service
57+
3. **Connect to Firestore** - Initializes secure Firestore connection
58+
4. **Fetch Your Profile** - Reads participant data and team assignment
59+
5. **Fetch Team API Keys** - Retrieves team-specific API keys
60+
6. **Fetch Global Configuration** - Fetches shared configuration keys
61+
7. **Create Environment File** - Generates .env file with all keys
62+
8. **Run Integration Test** - Validates API keys (optional)
63+
9. **Mark as Onboarded** - Updates participant status in Firestore
64+
65+
### Examples
66+
67+
**Basic Onboarding:**
68+
```bash
69+
export GITHUB_USER=myusername
70+
onboard \
71+
--bootcamp-name fall-2025 \
72+
--test-script tests/integration/test_api_keys.py
73+
```
74+
75+
**Skip Integration Tests:**
3176
```bash
3277
onboard \
3378
--bootcamp-name fall-2025 \
34-
--gcp-project coderd \
3579
--test-script tests/integration/test_api_keys.py \
36-
--output-dir .
80+
--skip-test
3781
```
3882

39-
#### Admin Status Report
83+
**Force Re-onboarding:**
84+
```bash
85+
onboard \
86+
--bootcamp-name fall-2025 \
87+
--test-script tests/integration/test_api_keys.py \
88+
--force
89+
```
4090

41-
View onboarding status for all participants (requires admin credentials):
91+
**Custom Output Directory:**
92+
```bash
93+
onboard \
94+
--bootcamp-name fall-2025 \
95+
--test-script tests/integration/test_api_keys.py \
96+
--output-dir ~/my-bootcamp
97+
```
4298

99+
**Admin Status Report:**
43100
```bash
101+
# Requires admin credentials
102+
gcloud auth application-default login
44103
onboard --admin-status-report --gcp-project coderd
45104
```
46105

106+
---
107+
47108
## Admin Commands
48109

110+
Admin commands for managing bootcamp participants and teams in Firestore.
111+
49112
### `onboard admin setup-participants`
50113

51-
Setup participants and teams from CSV file.
114+
Setup participants and teams from a CSV file. This command creates both team documents and participant documents in Firestore.
52115

53116
#### Usage
54117

55118
```bash
56-
onboard admin setup-participants <csv_file> [--dry-run]
119+
onboard admin setup-participants <csv_file> [OPTIONS]
57120
```
58121

59122
#### Arguments
@@ -73,6 +136,14 @@ Optional columns:
73136
- `first_name` - First name
74137
- `last_name` - Last name
75138

139+
**Sample CSV:**
140+
```csv
141+
github_handle,team_name,email,first_name,last_name
142+
alice,team-alpha,alice@example.com,Alice,Smith
143+
bob,team-alpha,bob@example.com,Bob,Jones
144+
charlie,team-beta,charlie@example.com,Charlie,Brown
145+
```
146+
76147
#### Options
77148

78149
| Option | Description |
@@ -83,134 +154,98 @@ Optional columns:
83154

84155
**Setup participants from CSV:**
85156
```bash
86-
onboard admin setup-participants participants.csv
157+
onboard admin setup-participants config/participants.csv
87158
```
88159

89160
**Dry run (validate only):**
90161
```bash
91-
onboard admin setup-participants participants.csv --dry-run
92-
```
93-
94-
**Sample CSV:**
95-
```csv
96-
github_handle,team_name,email,first_name,last_name
97-
alice,team-alpha,alice@example.com,Alice,Smith
98-
bob,team-alpha,bob@example.com,Bob,Jones
99-
charlie,team-beta,charlie@example.com,Charlie,Brown
162+
onboard admin setup-participants config/participants.csv --dry-run
100163
```
101164

102165
#### Requirements
103166

104167
- Admin credentials (service account or gcloud auth)
105168
- Firestore write access
106169

107-
## Options
108-
109-
### Required (for participant onboarding)
170+
---
110171

111-
| Option | Description | Example |
112-
|--------|-------------|---------|
113-
| `--bootcamp-name` | Name of the bootcamp | `--bootcamp-name fall-2025` |
114-
| `--test-script` | Path to integration test script | `--test-script tests/integration/test_api_keys.py` |
172+
### `onboard admin delete-participants`
115173

116-
### Optional
174+
Delete participants from Firestore database. Can optionally remove empty teams after participant deletion.
117175

118-
| Option | Description | Default |
119-
|--------|-------------|---------|
120-
| `--gcp-project` | GCP project ID | `coderd` |
121-
| `--output-dir` | Directory for .env file | `.` (current directory) |
122-
| `--firebase-api-key` | Firebase Web API key for token exchange | (from `FIREBASE_WEB_API_KEY` env var) |
123-
| `--skip-test` | Skip integration tests | `False` |
124-
| `--force` | Force re-onboarding even if already onboarded | `False` |
125-
| `--admin-status-report` | Display onboarding status for all participants (admin only) | `False` |
126-
| `--version` | Show version number and exit | - |
127-
128-
## Onboarding Process
176+
#### Usage
129177

130-
The participant onboarding flow consists of 9 steps:
178+
```bash
179+
onboard admin delete-participants <csv_file> [OPTIONS]
180+
```
131181

132-
1. **Identify Participant** - Detects GitHub username from environment
133-
2. **Fetch Authentication Token** - Retrieves fresh token from service
134-
3. **Connect to Firestore** - Initializes secure Firestore connection
135-
4. **Fetch Your Profile** - Reads participant data and team assignment
136-
5. **Fetch Team API Keys** - Retrieves team-specific API keys
137-
6. **Fetch Global Configuration** - Fetches shared configuration keys
138-
7. **Create Environment File** - Generates .env file with all keys
139-
8. **Run Integration Test** - Validates API keys (optional)
140-
9. **Mark as Onboarded** - Updates participant status in Firestore
182+
#### Arguments
141183

142-
## Environment Variables
184+
| Argument | Description | Required |
185+
|----------|-------------|----------|
186+
| `csv_file` | Path to CSV file with participants to delete | Yes |
143187

144-
The following environment variables are used:
188+
#### CSV Format
145189

146-
| Variable | Description | Required |
147-
|----------|-------------|----------|
148-
| `GITHUB_USER` | GitHub username for authentication | Yes |
149-
| `FIREBASE_WEB_API_KEY` | Firebase Web API key (can be passed via `--firebase-api-key`) | Yes |
150-
| `GOOGLE_APPLICATION_CREDENTIALS` | Path to GCP service account key (admin only) | For `--admin-status-report` |
190+
Required columns:
191+
- `github_handle` - GitHub username of participant to delete
151192

152-
## Exit Codes
193+
**Sample CSV:**
194+
```csv
195+
github_handle
196+
alice
197+
bob
198+
```
153199

154-
| Code | Description |
155-
|------|-------------|
156-
| `0` | Success |
157-
| `1` | Failure (authentication, connection, or configuration error) |
200+
#### Options
158201

159-
## Examples
202+
| Option | Description | Default |
203+
|--------|-------------|---------|
204+
| `--dry-run` | Validate and preview changes without modifying Firestore | `False` |
205+
| `--keep-empty-teams` | Keep teams even if they become empty after removing participants | `False` |
160206

161-
### Basic Onboarding
207+
#### Examples
162208

209+
**Delete participants from CSV:**
163210
```bash
164-
export GITHUB_USER=myusername
165-
onboard \
166-
--bootcamp-name fall-2025 \
167-
--test-script tests/integration/test_api_keys.py
211+
onboard admin delete-participants config/to_remove.csv
168212
```
169213

170-
### Skip Integration Tests
171-
214+
**Dry run (preview only):**
172215
```bash
173-
onboard \
174-
--bootcamp-name fall-2025 \
175-
--test-script tests/integration/test_api_keys.py \
176-
--skip-test
216+
onboard admin delete-participants config/to_remove.csv --dry-run
177217
```
178218

179-
### Force Re-onboarding
180-
219+
**Delete participants but keep empty teams:**
181220
```bash
182-
onboard \
183-
--bootcamp-name fall-2025 \
184-
--test-script tests/integration/test_api_keys.py \
185-
--force
221+
onboard admin delete-participants config/to_remove.csv --keep-empty-teams
186222
```
187223

188-
### Custom Output Directory
224+
#### Requirements
189225

190-
```bash
191-
onboard \
192-
--bootcamp-name fall-2025 \
193-
--test-script tests/integration/test_api_keys.py \
194-
--output-dir ~/my-bootcamp
195-
```
226+
- Admin credentials (service account or gcloud auth)
227+
- Firestore write access
196228

197-
### Admin Status Report
229+
---
198230

199-
```bash
200-
# Requires admin credentials
201-
gcloud auth application-default login
202-
onboard --admin-status-report --gcp-project coderd
203-
```
231+
## Environment Variables
204232

205-
### Setup Participants
233+
| Variable | Description | Required |
234+
|----------|-------------|----------|
235+
| `GITHUB_USER` | GitHub username for authentication | Yes (for participant onboarding) |
236+
| `FIREBASE_WEB_API_KEY` | Firebase Web API key (can be passed via `--firebase-api-key`) | Yes (for participant onboarding) |
237+
| `GOOGLE_APPLICATION_CREDENTIALS` | Path to GCP service account key | Yes (for admin commands) |
206238

207-
```bash
208-
# Setup participants from CSV
209-
onboard admin setup-participants config/participants.csv
239+
---
210240

211-
# Validate CSV without making changes
212-
onboard admin setup-participants config/participants.csv --dry-run
213-
```
241+
## Exit Codes
242+
243+
| Code | Description |
244+
|------|-------------|
245+
| `0` | Success |
246+
| `1` | Failure (authentication, connection, or configuration error) |
247+
248+
---
214249

215250
## Generated Files
216251

@@ -229,6 +264,8 @@ The onboarding process creates a `.env` file containing:
229264
source .env
230265
```
231266

267+
---
268+
232269
## Troubleshooting
233270

234271
### Authentication Failures
@@ -260,7 +297,8 @@ source .env
260297

261298
### CSV Validation Errors
262299

263-
- Check CSV has required columns: `github_handle`, `team_name`
300+
- Check CSV has required columns: `github_handle`, `team_name` (for setup-participants)
301+
- Check CSV has required column: `github_handle` (for delete-participants)
264302
- Verify GitHub handles are valid (alphanumeric and hyphens, max 39 chars)
265303
- Ensure team names are valid (alphanumeric, hyphens, underscores)
266-
- Check for duplicate GitHub handles
304+
- Check for duplicate GitHub handles in CSV

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "aieng-platform-onboard"
3-
version = "0.4.0"
3+
version = "0.5.0"
44
description = "CLI tool for onboarding participants to AI Engineering bootcamps"
55
readme = "README.md"
66
authors = [{name = "Vector AI Engineering", email = "ai_engineering@vectorinstitute.ai"}]

0 commit comments

Comments
 (0)