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

npm install -g @idp.global/cli
# or
pnpm add -g @idp.global/cli

Quick Start

# 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:

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

$ idp orgs-create
Organization Name: My Company
Organization Slug: my-company

Organization created successfully!
  ID: org_abc123
  Name: My Company

Invite Team Members

$ idp invite --org org_abc123 --email colleague@example.com
Invitation sent to colleague@example.com

View Active Sessions

$ 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 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.

readme.md

@idp.global/cli