feat(build): add tsbundle/tswatch configs, update build/watch scripts, bump dependencies, and add CLI documentation
This commit is contained in:
@@ -0,0 +1,195 @@
|
||||
# @idp.global/cli
|
||||
|
||||
Command-line interface for interacting with the idp.global Identity Provider. A Node.js CLI tool that provides authentication, user management, and organization administration from the terminal.
|
||||
|
||||
## Overview
|
||||
|
||||
The IdpCli module provides a complete command-line interface for managing your idp.global account and organizations. It uses file-based credential storage and WebSocket connections for real-time communication with the IdP server.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install -g @idp.global/cli
|
||||
# or
|
||||
pnpm add -g @idp.global/cli
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Login with email and password
|
||||
idp login
|
||||
|
||||
# Check current user
|
||||
idp whoami
|
||||
|
||||
# List your organizations
|
||||
idp orgs
|
||||
|
||||
# Logout
|
||||
idp logout
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### Authentication
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `idp login` | Interactive login with email and password |
|
||||
| `idp login-token` | Login with an API token |
|
||||
| `idp logout` | Clear stored credentials and end session |
|
||||
|
||||
### User Information
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `idp whoami` | Display current user information |
|
||||
| `idp sessions` | List all active sessions |
|
||||
| `idp revoke --session <id>` | Revoke a specific session |
|
||||
|
||||
### Organization Management
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `idp orgs` | List all organizations you belong to |
|
||||
| `idp orgs-create` | Create a new organization (interactive) |
|
||||
| `idp members --org <id>` | List members of an organization |
|
||||
| `idp invite --org <id> --email <email>` | Invite a user to an organization |
|
||||
|
||||
### Admin Commands (Global Admins Only)
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `idp admin-check` | Check if you are a global admin |
|
||||
| `idp admin-apps` | List all global apps with connection stats |
|
||||
| `idp admin-suspend --user <id>` | Suspend a user account |
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `IDP_URL` | Override the IdP server URL | `https://idp.global` |
|
||||
|
||||
### Credential Storage
|
||||
|
||||
Credentials are stored in `~/.idp-global/credentials.json`. This file contains your refresh token and JWT for persistent authentication across CLI sessions.
|
||||
|
||||
## Programmatic Usage
|
||||
|
||||
You can also use the IdpCli class programmatically:
|
||||
|
||||
```typescript
|
||||
import { IdpCli } from '@idp.global/cli';
|
||||
|
||||
const cli = new IdpCli({
|
||||
idpBaseUrl: 'https://idp.global',
|
||||
configDir: '/custom/config/path', // optional
|
||||
});
|
||||
|
||||
// Login
|
||||
await cli.loginWithPassword('user@example.com', 'password');
|
||||
|
||||
// Get current user
|
||||
const user = await cli.whoami();
|
||||
console.log('Logged in as:', user.data.name);
|
||||
|
||||
// Get organizations
|
||||
const { organizations, roles } = await cli.getOrganizations();
|
||||
for (const org of organizations) {
|
||||
console.log(`- ${org.data.name} (${org.id})`);
|
||||
}
|
||||
|
||||
// Disconnect when done
|
||||
await cli.disconnect();
|
||||
```
|
||||
|
||||
### IdpCli Class Methods
|
||||
|
||||
**Authentication:**
|
||||
- `loginWithPassword(email, password)` - Login with credentials
|
||||
- `loginWithApiToken(token)` - Login with API token
|
||||
- `refreshJwt()` - Refresh the current JWT
|
||||
- `logout()` - Clear credentials and end session
|
||||
|
||||
**User:**
|
||||
- `whoami()` - Get current user info
|
||||
- `getSessions()` - Get active sessions
|
||||
- `revokeSession(sessionId)` - Revoke a session
|
||||
|
||||
**Organizations:**
|
||||
- `getOrganizations()` - List user's organizations
|
||||
- `createOrganization(name, slug, mode)` - Create new organization
|
||||
- `getOrgMembers(orgId)` - Get organization members
|
||||
- `inviteMember(orgId, email, roles)` - Invite a user
|
||||
|
||||
**Admin:**
|
||||
- `checkGlobalAdmin()` - Check admin status
|
||||
- `getGlobalAppStats()` - Get app statistics
|
||||
- `suspendUser(userId)` - Suspend a user
|
||||
|
||||
## Examples
|
||||
|
||||
### Create an Organization
|
||||
|
||||
```bash
|
||||
$ idp orgs-create
|
||||
Organization Name: My Company
|
||||
Organization Slug: my-company
|
||||
|
||||
Organization created successfully!
|
||||
ID: org_abc123
|
||||
Name: My Company
|
||||
```
|
||||
|
||||
### Invite Team Members
|
||||
|
||||
```bash
|
||||
$ idp invite --org org_abc123 --email colleague@example.com
|
||||
Invitation sent to colleague@example.com
|
||||
```
|
||||
|
||||
### View Active Sessions
|
||||
|
||||
```bash
|
||||
$ idp sessions
|
||||
|
||||
Active Sessions:
|
||||
- sess_xyz789
|
||||
Device: MacBook Pro
|
||||
Browser: Chrome
|
||||
OS: macOS
|
||||
Last Active: 1/29/2025, 2:30:00 PM
|
||||
Current: Yes
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `@api.global/typedrequest` - Type-safe API requests
|
||||
- `@api.global/typedsocket` - WebSocket communication
|
||||
- `@push.rocks/smartcli` - CLI framework
|
||||
- `@push.rocks/smartinteract` - Interactive prompts
|
||||
- `@idp.global/interfaces` - TypeScript interfaces
|
||||
|
||||
## License and Legal Information
|
||||
|
||||
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](../LICENSE) file.
|
||||
|
||||
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
|
||||
|
||||
### Trademarks
|
||||
|
||||
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
|
||||
|
||||
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
|
||||
|
||||
### Company Information
|
||||
|
||||
Task Venture Capital GmbH
|
||||
Registered at District Court Bremen HRB 35230 HB, Germany
|
||||
|
||||
For any legal inquiries or further information, please contact us via email at hello@task.vc.
|
||||
|
||||
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
|
||||
Reference in New Issue
Block a user