RefWire CLI

RefWire CLI is an open-source, Node.js-based command-line tool for administering your RefWire 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/refwire

refwire dataset list-ids

This will prompt you for:

• RefWire Url: Your RefWire Instance URL e.g https://myrefwireeintance.com, https://localhost:7050
• ApiKey (Use 'ThisIsTheApiKey' for demo purposes but make sure to set a strong key for production via Configuration)
• RefStor Server Url (optional): Set this to https://refpack.refwire.online to use the refwire **pull** {datasetID} command which give you access to standardized datasets found at https://stor.refwire.online
• Note: You will only need to set the configuration only once

---

Overview

RefWire CLI streamlines administrative tasks for your RefWire 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 RefWire 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 (~/.refwiredb/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+), RefWire CLI uses Commander.js for command parsing, communicates with your RefWire Server’s REST API, and persists session data in ~/.refwiredb/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/refwire

Option 2: Install from Source

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

Verify installation:

refwire --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.refwire.online

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

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

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

---

Usage

Basic command syntax:

refwire <category> <command> [options]

Global Options

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

Command Categories

api-key — Manage API Keys

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

dataset — Manage Datasets

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 RefStor. Options:
-i, -n, -d, --id-field, --name-field

item — Manage Items

refwire item add      <datasetId> <itemId> "Name" -d '{"key":"value"}'
refwire 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.

health — System Diagnostics

Command	Description
report	View system health report.

instance — Instance Management

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

auth — Authentication

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

---

Examples

Create a Read-Only API Key

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

List All Dataset IDs

refwire dataset list-ids

Show Metadata for countries

refwire dataset get-meta countries

Delete a Dataset (with Prompt)

refwire dataset delete obsoleteDataset

Force-Delete Without Prompt

refwire dataset delete obsoleteDataset --force

Import via Wizard

refwire dataset import

Pull from RefStor

refwire 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: refwire dataset get-meta countries

Logout & Clear Credentials

refwire auth logout

Force Logout Without Prompt

refwire auth logout --force

Check Authentication Status

refwire auth status

Sample Output:

You are fully configured with the following settings:
Server URL: https://api.example.com
API Key: *******
Store URL: stor.refwire.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 info@coretravis.work.