CLI Overview

The ServiceHop CLI provides an interactive command-line interface for managing services, ingesting data, and running insight operations.

Architecture

Built on JLine 3, the CLI provides:

Interactive shell with command history
Tab completion for commands and parameters
Multiple output formats (TABLE, JSON, FORM, CSV)
Scripting support with quiet mode

Starting the CLI

From JAR

java -jar servicehop-cli-1.0.1.jar

From Native Executable

./servicehop-cli

Interactive Mode

ServiceHop CLI v1.0.1
Connected to: https://api.example.com
Token: shp_abc...xyz (expires: 2024-12-31)

servicehop> help

Non-Interactive Mode

echo "insight --list" | java -jar servicehop-cli-1.0.1.jar

Configuration

Environment Variables

Variable	Description	Default
`SERVICEHOP_API_URL`	ServiceHop Core URL	http://localhost:8080
`SERVICEHOP_API_TOKEN`	Authentication token	(required)

Configuration File

Location: ~/.servicehop/config

api.url=https://api.example.com
api.token=shp_your_token_here

Precedence

Environment variables (highest)
Configuration file
Defaults (lowest)

Command Structure

General Pattern

command [--parameter value] [argument]

Parameters

Named options prefixed with --:

Type	Example
FLAG	`--quiet`
STRING	`--output json`
INTEGER	`--page 2`
BOOLEAN	`--with-payload true`

Arguments

Positional values without prefix:

call --show abc123
       └─── argument (call ID)

Common Parameters

Available on most commands:

Parameter	Type	Description
`--quiet`	FLAG	Suppress non-data output
`--output`	STRING	Output format: json, table, form, csv
`--output-file`	STRING	Write output to file
`--page`	INTEGER	Page number (1-based)
`--page-size`	INTEGER	Items per page
`--sort`	STRING	Sort criteria (e.g., `timestamp,-service`)
`--columns`	STRING	Columns to display
`--service`	STRING	Filter by service
`--yes`	FLAG	Auto-confirm prompts

Output Formats

TABLE (default for lists)

┌──────────────────────────────────────┬─────────────┬────────────┐
│ ID                                   │ Service     │ Status     │
├──────────────────────────────────────┼─────────────┼────────────┤
│ abc-123                              │ user-svc    │ READY      │
│ def-456                              │ order-svc   │ WORKING    │
└──────────────────────────────────────┴─────────────┴────────────┘

FORM (default for single items)

ID:        abc-123
Service:   user-svc
Status:    READY
Timestamp: 2024-01-15T10:30:00Z

JSON

{
  "id": "abc-123",
  "service": "user-svc",
  "status": "READY"
}

CSV

id,service,status
abc-123,user-svc,READY
def-456,order-svc,WORKING

Pagination

Request Parameters

--page 2 --page-size 25

Response Information

Page 2 of 5 (25 items per page, 112 total)

Sorting

--sort timestamp        # ascending
--sort -timestamp       # descending
--sort service,-timestamp  # multiple fields

Interactive Features

Command History

Up/Down arrows: Navigate history
Ctrl+R: Search history
History persisted across sessions

Tab Completion

Commands: ins<TAB> → insight
Parameters: --out<TAB> → --output
Values: --output <TAB> → json, table, form, csv

Confirmation Prompts

servicehop> insight --orchestrate
This will run orchestration for all services. Continue? [Y/n]

Skip with --yes:

servicehop> insight --orchestrate --yes

Exit Codes

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	API error
4	Authentication error

Scripting Tips

Quiet Mode

# Suppress headers, footers, and prompts
servicehop-cli --quiet insight --list --output json

Piping

# Process JSON output with jq
servicehop-cli insight --list --output json | jq '.[] | .id'

File Output

# Save to file
servicehop-cli call --list --output csv --output-file calls.csv