ListServ CLI

ListServ CLI is an open-source, Node.js-based command-line tool for administering your ListServ instance(s) via its RESTful API. It provides a consistent, interactive, and scriptable interface for:

• API Key Management
• Dataset Operations
• Item Management
• System Health & Instance Administration
• Credential & Session Management

Table of Contents

• Quick Start

• Overview

• Features

• Architecture & Context

• Installation

• Configuration & Authentication

• Usage

  • Global Options
  • Command Categories

• Examples

• Contributing

• License

• Contact

Quick Start

npm install -g @coretravis/listserv-cli
export LISTSERV_URL=https://api.example.com
export LISTSERV_API_KEY=your_api_key_here

listserv dataset list-ids

Overview

ListServ CLI streamlines administrative tasks for your ListServ data service:

• Securely create, list, update, and revoke API keys.
• Import, update, and delete datasets—with an interactive JSON import wizard.
• Add, update, or archive items individually or in bulk.
• Monitor system health and manage distributed application instances.
• Persist credentials across sessions using environment variables or a local config file.

Features

API Key Management

• Create keys (30-day default TTL).
• List & Retrieve key details.
• Update & Revoke keys on demand.

Dataset Operations

• Non-Interactive Create/Update from local JSON files.
• Interactive Import Wizard for guided dataset creation.
• Pull datasets from ListServ Stor with automatic ID/Name field detection.
• Inspect metadata and API schemas.
• Delete datasets with confirmation and item-count warnings.

Item Management

• Add/Update single items or bulk-load via JSON files.
• Archive (soft-delete) items to preserve history.

System Administration & Orchestration

• Health Reporting: view system diagnostics.
• Instance Management: list/remove distributed app instances (leader/follower).
• System Snapshot: capture full system state (datasets, instances, health).
• Security: rate limiting, CORS support, and credential validation included.

Session & Credential Management

• Credentials are sourced in this order:

  1. Environment variables
  2. Local config file (~/.listservdb/config.json)
  3. Interactive prompts

• logout command to clear saved credentials.

• status command to inspect your current authentication config.

Architecture & Context

Built with Node.js (v14+), ListServ CLI uses Commander.js for command parsing, communicates with your ListServ Server’s REST API, and persists session data in ~/.listservdb/config.json.

Installation

Prerequisites

• Node.js v14 or newer
• npm (comes with Node.js)
• Docker (optional—for containerized builds)

Option 1: Install via npm (Recommended)

npm install -g @coretravis/listserv-cli

Option 2: Install from Source

git clone https://github.com/coretravis/ListServCLI.git
cd ListServCLI
npm install
npm run build         # only if modifying source
npm link              # makes `listserv` available globally

Verify installation:

listserv --help

Configuration & Authentication

The CLI retrieves your server configuration from the following, in order:

1. Environment Variables

   export LISTSERV_URL=https://api.example.com
   export LISTSERV_API_KEY=your_api_key_here
   export LISTSERV_STORE_URL=stor.listserv.online

2. Local Config File (~/.listservdb/config.json)

   {
     "url": "https://api.example.com",
     "apiKey": "your_saved_api_key",
     "storeUrl": "stor.listserv.online"
   }

3. Interactive Prompts If no credentials are found, the CLI will prompt for them and save the configuration locally.

Usage

Basic command syntax:

listserv <category> <command> [options]

Global Options

• --version — Show CLI version
• --help — Show help for CLI or specific command

Command Categories

listserv api-key create "WebKey" -d "Public access" -s read

| Command | Description | | --------------- | ---------------------------------------------------------- | | create <name> | Create new key (30-day TTL). Supports -d, -s. | | list | List all API keys. | | get <id> | Show details for a specific API key. | | update <id> | Update name, description, or scopes (replaces old scopes). | | revoke <id> | Delete a specific API key. |

| Command | Description | | -------------------------------------------------- | --------------------------------------------------- | | list-ids | List all dataset IDs. | | get-meta <id> | View dataset metadata. | | get-api <id> | View dataset API schema. | | get-state | Full system snapshot (datasets, instances, health). | | delete <id> [--force] | Delete dataset, confirm unless --force. | | create --file <path> | Create dataset from JSON file. | | update <id> --file <path> | Update dataset from file. | | import | Launch interactive import wizard. | | pull <liststorId> | Download from ListStor. Options: | |     -i, -n, -d, --id-field, --name-field | |

listserv item add      <datasetId> <itemId> "Name" -d '{"key":"value"}'
listserv item add-bulk <datasetId> --file items.json

| Command | Description | | ---------- | ------------------------- | | add | Add single item. | | add-bulk | Add items from JSON file. | | update | Update item fields. | | archive | Soft-delete item. |

| Command | Description | | -------- | -------------------------- | | report | View system health report. |

| Command | Description | | ------------- | --------------------------- | | list | List registered instances. | | remove <id> | Remove a specific instance. |

| Command | Description | | ------------------ | --------------------------------------------------- | | logout [--force] | Clears saved credentials. Prompts unless --force. | | status | Shows current authentication setup. |

Examples

Create a Read-Only API Key

listserv api-key create "WebClientKey" -d "Key for public web app" -s read

List All Dataset IDs

listserv dataset list-ids

Show Metadata for countries

listserv dataset get-meta countries

Delete a Dataset (with Prompt)

listserv dataset delete obsoleteDataset

Force-Delete Without Prompt

listserv dataset delete obsoleteDataset --force

Import via Wizard

listserv dataset import

Pull from ListStor

listserv dataset pull world-countries \
  --id countries \
  --name "All Countries" \
  --description "ISO country list" \
  --id-field iso2 \
  --name-field name

On success:

Dataset 'countries' successfully pulled and created!
View details with: listserv dataset get-meta countries

Logout & Clear Credentials

listserv auth logout

Force Logout Without Prompt

listserv auth logout --force

Check Authentication Status

listserv auth status

Sample Output:

You are fully configured with the following settings:
Server URL: https://api.example.com
API Key: *******
Store URL: stor.listserv.online (default)

Using environment variables: LISTSERV_URL, LISTSERV_API_KEY

Contributing

We welcome all contributions! See our CONTRIBUTING guide for:

• Fork & branch workflow
• Coding standards
• Linting & testing
• PR guidelines

Use GitHub Discussions to propose features or report bugs.

License

MIT License — see LICENSE.

Contact

For support or questions, use GitHub Discussions or email [email protected].