# @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.