idp.global/app
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(docs): refresh module readmes and add repository license file

Browse Source
This commit is contained in:
Jürgen Kunz
2026-04-20 08:15:42 +00:00
parent 2d1e6ea6e1
commit 76efcb835f
10 changed files with 511 additions and 1286 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ts_idpcli/readme.md
+49 -133
View File
@@ -1,181 +1,97 @@
# @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.
Terminal client for `idp.global`.
## Overview
It wraps the same typed backend used by the web app and SDK, but stores credentials on disk so you can inspect accounts, sessions, orgs, and admin state from the shell.
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.
## Issue Reporting and Security
## Installation
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
## Install
```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
idp sessions
```
## 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 |
| Command | Purpose |
| --- | --- |
| `idp login` | Prompt for email and password |
| `idp login-token` | Prompt for an API token |
| `idp logout` | Remove local credentials and try server-side logout |
| `idp whoami` | Print the current user |
| `idp sessions` | List active sessions |
| `idp revoke --session <session-id>` | Revoke a session |
| `idp orgs` | List organizations for the current user |
| `idp orgs-create` | Interactively create an organization |
| `idp members --org <org-id>` | List members for an organization |
| `idp invite --org <org-id> --email user@example.com` | Invite a member |
| `idp admin-check` | Check global admin status |
| `idp admin-apps` | List global app stats |
| `idp admin-suspend --user <user-id>` | Suspend a user |
## Configuration
### Environment Variables
The CLI reads `IDP_URL` and defaults to `https://idp.global`.
| Variable | Description | Default |
|----------|-------------|---------|
| `IDP_URL` | Override the IdP server URL | `https://idp.global` |
```bash
IDP_URL=http://localhost:2999 idp whoami
```
### Credential Storage
Credentials are stored in:
Credentials are stored in `~/.idp-global/credentials.json`. This file contains your refresh token and JWT for persistent authentication across CLI sessions.
```text
~/.idp-global/credentials.json
```
## Programmatic Usage
You can also use the IdpCli class programmatically:
```typescript
```ts
import { IdpCli } from '@idp.global/cli';
const cli = new IdpCli({
idpBaseUrl: 'https://idp.global',
configDir: '/custom/config/path', // optional
idpBaseUrl: 'http://localhost:2999',
});
// Login
await cli.loginWithPassword('user@example.com', 'password');
await cli.loginWithPassword('user@example.com', 'secret');
// Get current user
const user = await cli.whoami();
console.log('Logged in as:', user.data.name);
const me = await cli.whoami();
const orgs = await cli.getOrganizations();
// Get organizations
const { organizations, roles } = await cli.getOrganizations();
for (const org of organizations) {
console.log(`- ${org.data.name} (${org.id})`);
}
console.log(me?.data?.email);
console.log(orgs?.organizations.length);
// Disconnect when done
await cli.disconnect();
```
### IdpCli Class Methods
## What The Class Exposes
**Authentication:**
- `loginWithPassword(email, password)` - Login with credentials
- `loginWithApiToken(token)` - Login with API token
- `refreshJwt()` - Refresh the current JWT
- `logout()` - Clear credentials and end session
- `loginWithPassword()` and `loginWithApiToken()`
- `refreshJwt()` and `logout()`
- `whoami()`, `getSessions()`, and `revokeSession()`
- `getOrganizations()`, `createOrganization()`, `getOrgMembers()`, and `inviteMember()`
- `checkGlobalAdmin()`, `getGlobalAppStats()`, and `suspendUser()`
**User:**
- `whoami()` - Get current user info
- `getSessions()` - Get active sessions
- `revokeSession(sessionId)` - Revoke a session
## Implementation Notes
**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
- The CLI connects to the backend websocket surface at `/typedrequest`.
- It uses file-based credentials instead of browser storage.
- `orgs-create` first checks availability, then creates the organization.
## 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.
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.
@@ -187,7 +103,7 @@ Use of these trademarks must comply with Task Venture Capital GmbH's Trademark G
### Company Information
Task Venture Capital GmbH
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.