Skip to content

Commit cc590b0

Browse files
nicknisinicknisi
authored
feat: add environment, organization, and user management commands (#59)
* feat: add environment management commands and config store Add `workos env` command group (add/remove/switch/list) for managing multiple environments with API keys. Introduces a keyring-backed config store (with file fallback) separate from OAuth credentials, and an API key resolution utility for upcoming management commands. * feat: add organization management commands Add `workos organization` command group (create/update/get/list/delete) for managing WorkOS organizations via the REST API. Includes a generic WorkOS API client for reuse with future resource types and a table formatter for list output. * chore: formatting * feat: add user management commands Add `workos user` command group (get/list/update/delete) for managing WorkOS users via the REST API, porting Go CLI PR #24. * chore: formatting * docs: update README, DEVELOPMENT, and CLAUDE.md for management commands * chore: remove accidentally committed .claude and docs directories * feat: reconcile credential stores for seamless management commands After install fetches staging credentials, auto-seed a "default" environment in config-store so management commands work without manual `workos env add`. Subsequent installs read from config-store and skip the staging API call when clientId + apiKey are present.
1 parent 0ef8127 commit cc590b0

18 files changed

Lines changed: 2236 additions & 73 deletions

‎CLAUDE.md‎

Lines changed: 46 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,39 @@
1-
# installer
1+
# workos CLI
22

3-
AI-powered CLI installer that automatically installs WorkOS AuthKit into web projects.
3+
WorkOS CLI for installing AuthKit integrations and managing WorkOS resources (organizations, users, environments).
44

55
## Project Structure
66

77
```
8-
installer/
9-
├── src/
10-
│ ├── bin.ts # CLI entry point
11-
│ ├── cli.config.ts # App configuration (model, URLs, etc.)
12-
│ ├── run.ts # Entry point, orchestrates installer flow
13-
│ ├── lib/
14-
│ │ ├── agent-interface.ts # Claude Agent SDK integration
15-
│ │ ├── agent-runner.ts # Builds prompts, runs agent
16-
│ │ ├── config.ts # Framework detection config
17-
│ │ ├── constants.ts # Integration enum, shared constants
18-
│ │ ├── credential-proxy.ts # Token refresh proxy for long sessions
19-
│ │ └── ensure-auth.ts # Startup auth guard with token refresh
20-
│ ├── dashboard/ # Ink/React TUI components
21-
│ ├── nextjs/ # Next.js installer agent
22-
│ ├── react/ # React SPA installer agent
23-
│ ├── react-router/ # React Router installer agent
24-
│ ├── tanstack-start/ # TanStack Start installer agent
25-
│ └── vanilla-js/ # Vanilla JS installer agent
26-
└── ...
8+
src/
9+
├── bin.ts # CLI entry point (yargs command routing)
10+
├── cli.config.ts # App configuration (model, URLs, etc.)
11+
├── run.ts # Installer orchestration entry point
12+
├── lib/
13+
│ ├── agent-interface.ts # Claude Agent SDK integration
14+
│ ├── agent-runner.ts # Builds prompts, runs agent
15+
│ ├── config.ts # Framework detection config
16+
│ ├── constants.ts # Integration enum, shared constants
17+
│ ├── credential-store.ts # OAuth credential storage (keyring + file fallback)
18+
│ ├── config-store.ts # Environment config storage (keyring + file fallback)
19+
│ ├── api-key.ts # API key resolution (env var → flag → config)
20+
│ ├── workos-api.ts # Generic WorkOS REST API client
21+
│ ├── credential-proxy.ts # Token refresh proxy for long sessions
22+
│ └── ensure-auth.ts # Startup auth guard with token refresh
23+
├── commands/
24+
│ ├── env.ts # workos env (add/remove/switch/list)
25+
│ ├── organization.ts # workos organization (create/update/get/list/delete)
26+
│ ├── user.ts # workos user (get/list/update/delete)
27+
│ ├── install.ts # workos install
28+
│ └── login.ts / logout.ts # Auth commands
29+
├── dashboard/ # Ink/React TUI components
30+
├── nextjs/ # Next.js installer agent
31+
├── react/ # React SPA installer agent
32+
├── react-router/ # React Router installer agent
33+
├── tanstack-start/ # TanStack Start installer agent
34+
├── vanilla-js/ # Vanilla JS installer agent
35+
└── utils/
36+
└── table.ts # Terminal table formatter
2737
```
2838

2939
## Key Architecture
@@ -32,6 +42,8 @@ installer/
3242
- **Event Emitter**: `InstallerEventEmitter` bridges agent execution ↔ TUI for real-time updates
3343
- **Framework Detection**: Each integration has a `detect()` function in `config.ts`
3444
- **Permission Hook**: `installerCanUseTool()` in `agent-interface.ts` restricts Bash to safe commands only
45+
- **Config Store**: `config-store.ts` stores environment configs (API keys, endpoints) in system keyring with file fallback
46+
- **WorkOS API Client**: `workos-api.ts` is a generic fetch wrapper for any WorkOS REST endpoint
3547

3648
## CLI Modes
3749

@@ -93,11 +105,16 @@ pnpm test # Run tests
93105
pnpm typecheck # Type check
94106
```
95107

96-
## Testing the Installer
108+
## Testing
97109

98110
```bash
99111
# Run installer in a test project
100112
cd /path/to/test-app && workos dashboard
113+
114+
# Test management commands
115+
workos env add sandbox sk_test_xxx
116+
workos organization list
117+
workos user list
101118
```
102119

103120
## Adding a New Framework
@@ -106,3 +123,10 @@ cd /path/to/test-app && workos dashboard
106123
2. Add to `Integration` enum in `lib/constants.ts`
107124
3. Add detection logic in `lib/config.ts`
108125
4. Wire up in `run.ts` switch statement
126+
127+
## Adding a New Resource Command
128+
129+
1. Create `src/commands/{resource}.ts` with command handlers (uses `workos-api.ts`)
130+
2. Create `src/commands/{resource}.spec.ts` with mocked API tests
131+
3. Register in `src/bin.ts` as a yargs command group with subcommands
132+
4. Commands use `resolveApiKey()` from `api-key.ts` for auth

‎DEVELOPMENT.md‎

Lines changed: 43 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -3,39 +3,43 @@
33
## Project Structure
44

55
```
6-
installer/
7-
├── src/
8-
│ ├── bin.ts # CLI entry point
9-
│ ├── cli.config.ts # App configuration (model, URLs)
10-
│ ├── run.ts # Entry point
11-
│ ├── lib/
12-
│ │ ├── agent-runner.ts # Core agent execution
13-
│ │ ├── agent-interface.ts # SDK interface
14-
│ │ ├── installer-core.ts # Headless installer core
15-
│ │ ├── config.ts # Framework detection config
16-
│ │ ├── framework-config.ts # Framework definitions
17-
│ │ ├── constants.ts # Integration types
18-
│ │ ├── events.ts # InstallerEventEmitter
19-
│ │ ├── credential-proxy.ts # Token refresh proxy for long sessions
20-
│ │ ├── ensure-auth.ts # Startup auth guard
21-
│ │ ├── background-refresh.ts # Background token refresh
22-
│ │ └── adapters/ # CLI and dashboard adapters
23-
│ ├── commands/ # Subcommands (install-skill, login, logout)
24-
│ ├── steps/ # Installer step implementations
25-
│ ├── dashboard/ # Ink/React TUI components
26-
│ ├── nextjs/ # Next.js installer agent
27-
│ ├── react/ # React SPA installer agent
28-
│ ├── react-router/ # React Router installer agent
29-
│ ├── tanstack-start/ # TanStack Start installer agent
30-
│ ├── vanilla-js/ # Vanilla JS installer agent
31-
│ └── utils/
32-
│ ├── clack-utils.ts # CLI prompts
33-
│ ├── debug.ts # Logging with redaction
34-
│ ├── redact.ts # Credential redaction
35-
│ ├── package-manager.ts # Package manager detection
36-
│ └── ... # Additional utilities
37-
├── tsconfig.json # TypeScript config
38-
└── package.json # Dependencies and scripts
6+
src/
7+
├── bin.ts # CLI entry point (yargs command routing)
8+
├── cli.config.ts # App configuration (model, URLs)
9+
├── run.ts # Installer orchestration entry point
10+
├── lib/
11+
│ ├── agent-runner.ts # Core agent execution
12+
│ ├── agent-interface.ts # Claude Agent SDK interface
13+
│ ├── installer-core.ts # Headless installer core (XState)
14+
│ ├── config.ts # Framework detection config
15+
│ ├── constants.ts # Integration types, shared constants
16+
│ ├── credential-store.ts # OAuth credential storage (keyring + file fallback)
17+
│ ├── config-store.ts # Environment config storage (keyring + file fallback)
18+
│ ├── api-key.ts # API key resolution (env var → flag → config)
19+
│ ├── workos-api.ts # Generic WorkOS REST API client
20+
│ ├── credential-proxy.ts # Token refresh proxy for long sessions
21+
│ ├── ensure-auth.ts # Startup auth guard
22+
│ └── adapters/ # CLI and dashboard adapters
23+
├── commands/
24+
│ ├── env.ts # workos env (add/remove/switch/list)
25+
│ ├── organization.ts # workos organization (create/update/get/list/delete)
26+
│ ├── user.ts # workos user (get/list/update/delete)
27+
│ ├── install.ts # workos install
28+
│ ├── install-skill.ts # workos install-skill
29+
│ ├── login.ts # workos login
30+
│ └── logout.ts # workos logout
31+
├── dashboard/ # Ink/React TUI components
32+
├── nextjs/ # Next.js installer agent
33+
├── react/ # React SPA installer agent
34+
├── react-router/ # React Router installer agent
35+
├── tanstack-start/ # TanStack Start installer agent
36+
├── vanilla-js/ # Vanilla JS installer agent
37+
└── utils/
38+
├── table.ts # Terminal table formatter
39+
├── clack-utils.ts # CLI prompts
40+
├── debug.ts # Logging with redaction
41+
├── redact.ts # Credential redaction
42+
└── ... # Additional utilities
3943
```
4044

4145
## Setup
@@ -54,9 +58,14 @@ pnpm build
5458
# Build, link globally, and watch for changes
5559
pnpm dev
5660

57-
# Test locally in another project
61+
# Test installer in another project
5862
cd /path/to/test/nextjs-app
5963
workos dashboard
64+
65+
# Test management commands
66+
workos env add sandbox sk_test_xxx
67+
workos organization list
68+
workos user list
6069
```
6170

6271
## Commands

‎README.md‎

Lines changed: 51 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# workos
22

3-
AI-powered CLI that automatically integrates WorkOS AuthKit into web applications.
3+
WorkOS CLI for installing AuthKit integrations and managing WorkOS resources.
44

55
## Installation
66

@@ -45,29 +45,65 @@ Get your credentials from [dashboard.workos.com](https://dashboard.workos.com):
4545
## CLI Options
4646

4747
```bash
48-
workos [options] [command]
48+
workos [command]
4949

5050
Commands:
51-
dashboard Run with visual TUI dashboard (experimental)
51+
install Install WorkOS AuthKit into your project
52+
dashboard Run installer with visual TUI dashboard (experimental)
5253
login Authenticate with WorkOS via Connect OAuth device flow
5354
logout Remove stored credentials
54-
install-skill Install AuthKit skills to coding agents (Claude Code, Codex, etc.)
55-
--list, -l List available skills without installing
56-
--skill, -s Install specific skill(s)
57-
--agent, -a Target agent(s): claude-code, codex, cursor, goose
55+
env Manage environment configurations
56+
organization Manage organizations
57+
user Manage users
58+
doctor Diagnose WorkOS integration issues
59+
install-skill Install AuthKit skills to coding agents
60+
```
61+
62+
### Environment Management
63+
64+
```bash
65+
workos env add [name] [apiKey] # Add environment (interactive if no args)
66+
workos env remove <name> # Remove an environment
67+
workos env switch [name] # Switch active environment
68+
workos env list # List environments with active indicator
69+
```
70+
71+
API keys are stored in the system keychain via `@napi-rs/keyring`, with a JSON file fallback at `~/.workos/config.json`.
72+
73+
### Organization Management
74+
75+
```bash
76+
workos organization create <name> [domain:state ...]
77+
workos organization update <orgId> <name> [domain] [state]
78+
workos organization get <orgId>
79+
workos organization list [--domain] [--limit] [--before] [--after] [--order]
80+
workos organization delete <orgId>
81+
```
82+
83+
### User Management
84+
85+
```bash
86+
workos user get <userId>
87+
workos user list [--email] [--organization] [--limit] [--before] [--after] [--order]
88+
workos user update <userId> [--first-name] [--last-name] [--email-verified] [--password] [--external-id]
89+
workos user delete <userId>
90+
```
91+
92+
Management commands resolve API keys via: `WORKOS_API_KEY` env var → `--api-key` flag → active environment's stored key.
93+
94+
### Installer Options
95+
96+
```bash
97+
workos install [options]
5898

59-
Options:
6099
--direct, -D Use your own Anthropic API key (bypass llm-gateway)
61100
--integration <name> Framework: nextjs, react, react-router, tanstack-start, vanilla-js
62-
--redirect-uri <uri> Custom redirect URI (defaults to framework convention)
63-
--homepage-url <url> Custom homepage URL (defaults to http://localhost:{port})
101+
--redirect-uri <uri> Custom redirect URI
102+
--homepage-url <url> Custom homepage URL
64103
--install-dir <path> Installation directory
65-
--no-validate Skip post-installation validation (includes build check)
104+
--no-validate Skip post-installation validation
66105
--force-install Force install packages even if peer dependency checks fail
67106
--debug Enable verbose logging
68-
69-
Environment Variables:
70-
WORKOS_TELEMETRY=false Disable telemetry collection
71107
```
72108
73109
## Examples
@@ -95,7 +131,7 @@ workos login
95131
workos logout
96132
```
97133
98-
Credentials are stored in `~/.workos/credentials.json`. Access tokens are not persisted long-term for security - users re-authenticate when tokens expire.
134+
OAuth credentials are stored in the system keychain (with `~/.workos/credentials.json` fallback). Access tokens are not persisted long-term for security - users re-authenticate when tokens expire.
99135
100136
## How It Works
101137

0 commit comments

Comments
 (0)