Overview

Quick Start

Installation

npm install json-type-cli

Basic Usage

import{createCli}from'json-type-cli';import{ObjectValue}from'@jsonjoy.com/json-type/lib/value/ObjectValue';// Create a router with your methodsconstrouter=ObjectValue.create().prop('greet',t.Function(t.Object(t.prop('name',t.str)),// Request schemat.Object(t.prop('message',t.str))// Response schema).options({title:'Greet a person',description:'Returns a greeting message for the given name'}),async({ name})=>({message:`Hello,${name}!`}));// Create and run CLIconstcli=createCli({  router,version:'v1.0.0',cmd:'my-cli'});cli.run();

node my-cli.js greet'{"name": "World"}'# Output: {"message": "Hello, World!"}node my-cli.js greet --str/name=Alice# Output: {"message": "Hello, Alice!"}

JSON Rx RPC Protocol Implementation

Request/Response Pattern

JSON Rx RPC Message Flow

Building CLI Tools

Defining Methods

import{createCli}from'json-type-cli';import{ObjectValue}from'@jsonjoy.com/json-type/lib/value/ObjectValue';constrouter=ObjectValue.create();const{ t}=router;// Simple echo methodrouter.prop('echo',t.Function(t.any,t.any).options({title:'Echo input',description:'Returns the input unchanged'}),async(input)=>input);// Math operationsrouter.prop('math.add',t.Function(t.Object(t.prop('a',t.num),t.prop('b',t.num)),t.Object(t.prop('result',t.num))).options({title:'Add two numbers',description:'Adds two numbers and returns the result'}),async({ a, b})=>({result:a+b}));// File processingrouter.prop('file.process',t.Function(t.Object(t.prop('filename',t.str),t.propOpt('encoding',t.str)),t.Object(t.prop('size',t.num),t.prop('content',t.str))).options({title:'Process a file',description:'Reads and processes a file'}),async({ filename, encoding='utf8'})=>{constfs=require('fs');constcontent=fs.readFileSync(filename,encoding);return{size:content.length,content:content};});

Organizing Routes

// routes/user.tsexportconstdefineUserRoutes=<RoutesextendsObjectType<any>>(r:ObjectValue<Routes>)=>{returnr.extend((t,r)=>[r('user.create',t.Function(t.Object(t.prop('name',t.str),t.prop('email',t.str)),t.Object(t.prop('id',t.str),t.prop('name',t.str),t.prop('email',t.str))).options({title:'Create a user',description:'Creates a new user account'}),async({ name, email})=>({id:generateId(),        name,        email})),r('user.get',t.Function(t.Object(t.prop('id',t.str)),t.Object(t.prop('id',t.str),t.prop('name',t.str),t.prop('email',t.str))).options({title:'Get user by ID',description:'Retrieves user information by ID'}),async({ id})=>getUserById(id))]);};// main.tsimport{defineUserRoutes}from'./routes/user';constrouter=defineUserRoutes(ObjectValue.create());constcli=createCli({ router});

Input Sources (Request Composition)

1. Command Line JSON Parameter

my-cli greet'{"name": "Alice", "age": 30}'my-cli math.add'{"a": 5, "b": 3}'

2. STDIN Input

echo'{"name": "Bob"}'| my-cli greetcat user.json| my-cli user.createcurl -s api.example.com/data.json| my-cli process.data

3. Command Line Options

# String valuesmy-cli greet --str/name=Alice --str/title="Ms."# Numeric valuesmy-cli math.add --num/a=10 --num/b=20# Boolean valuesmy-cli user.update --bool/active=true --bool/verified=false# JSON valuesmy-cli config.set --json/settings='{"theme": "dark", "lang": "en"}'# Nested paths using JSON Pointer (requires parent structure to exist)my-cli user.update'{"profile": {}}' --str/profile/name="Alice" --num/profile/age=25# To create nested structures, provide the base structure firstmy-cli config.set'{"database": {}}' --str/database/host=localhost --num/database/port=5432

Combining Input Sources

echo'{"name": "Default", "age": 0}'| my-cli greet --str/name=Alice --num/age=30# Result: {"name": "Alice", "age": 30}

Output Formats (Response Encoding)

Supported Codecs

Using Output Formats

# Default JSON outputmy-cli user.get'{"id": "123"}'# Pretty-printed JSONmy-cli user.get'{"id": "123"}' --format=json4# Binary formatsmy-cli data.export --format=cbor> data.cbormy-cli data.export --format=msgpack> data.msgpack# Text visualizationmy-cli config.get --format=treemy-cli config.get --format=text# Different input/output formatscat data.cbor| my-cli process.data --format=cbor:jsonecho'{"test": 123}'| my-cliecho --format=json:tree

Extracting Response Data

# Extract specific fieldmy-cli user.get'{"id": "123"}' --out=/user/name# Extract nested datamy-cli api.fetch'{"url": "example.com"}' --out=/response/data/items# Combine with format conversionmy-cli data.complex --out=/results/summary --format=json:text

Command Line Parameters

Data Type Parameters

String Values (--str or--s)

my-cli greet --str/name=Alicemy-cli config.set --s/database/host=localhost --s/database/name=mydb

Numeric Values (--num or--n)

my-cli math.add --num/a=10 --num/b=20my-cli server.start --n/port=3000 --n/workers=4

Boolean Values (--bool or--b)

my-cli user.update --bool/active=truemy-cli feature.toggle --b/enabled=false

JSON Values (--json or--j)

my-cli config.merge --json/settings='{"theme": "dark"}'my-cli api.call --j/payload='[1,2,3]'

Undefined Values (--und)

my-cli optional.field --und/optionalParam

File Input (--file or--f)

# Read JSON filemy-cli process.data --file/input=data.json# Read with specific codecmy-cli import.data --f/data=data.cbor:cbor# Extract path from filemy-cli user.create --f/profile=user.json:json:/personalInfo# Chain: file -> codec -> pathmy-cli complex.import --f/config=settings.msgpack:msgpack:/database/credentials

Command Execution (--cmd or--c)

# Use command output as stringmy-cli log.write --cmd/message='(echo "Current time: $(date)"):text'# Use command output as JSONmy-cli api.send --c/data='(curl -s api.example.com/data):json'# Extract path from command outputmy-cli process.status --c/info='(ps aux | grep node):json:/0/pid'

Format Control (--format or--fmt)

# Single format (for both input and output)my-cliecho --format=cbor# Separate input and output formatsmy-cli convert --format=cbor:jsonmy-cli transform --fmt=json:tree

STDIN Control (--stdin or--in)

# Use all STDIN dataecho'{"name": "Alice"}'| my-cli greet --stdin# Map STDIN to specific pathecho'{"users": [...]}'| my-cli process.users --in/data=/users# Map with path extractionecho'{"response": {"users": [...]}}'| my-cli save.users --in/users=/response/users

Output Control (--stdout or--out)

# Extract single fieldmy-cli user.get'{"id": "123"}' --out=/name# Extract nested objectmy-cli api.fetch --out=/response/data# Use with format conversionmy-cli complex.data --out=/results --format=json:tree

Utility Parameters

Help (--help or--h)

my-cli --help# General helpmy-cli method.name --help# Method-specific help

Version (--version or--v)

my-cli --version

Execution Plan (--plan)

my-cli complex.operation --plan# Show what would be executed

Advanced Features

Type Introspection

# List all methodsmy-cli .type# Get method schemamy-cli .type --out=/methodNamemy-cli .type --out=/user.create/req --format=treemy-cli .type --out=/user.create/res --format=json4

Binary Data Handling

# Process binary datacat image.jpg| my-cli image.process --format=raw:json# Convert between binary formatscat data.cbor| my-cli convert --format=cbor:msgpack> data.msgpack# Encode JSON as binarymy-cli data.export'{"large": "dataset"}' --format=json:cbor> export.cbor

Error Handling

my-cli invalid.method2>errors.logmy-cli user.get'{"invalid": "data"}'2>validation-errors.json

Performance Optimization

# Use binary formats for large datamy-cli large.dataset --format=msgpack# Use raw format for simple string/binary outputmy-cli get.file.content --format=raw# Stream processing with STDIN/STDOUTcat large-file.json| my-cli process.stream --format=json:cbor| my-cli save.processed --format=cbor

Complete Example

import{createCli}from'@jsonjoy.com/json-type-cli';import{ObjectValue}from'@jsonjoy.com/json-type/lib/value/ObjectValue';import*asfsfrom'fs';import*aspathfrom'path';constrouter=ObjectValue.create();const{ t}=router;// File operationsrouter.prop('file.read',t.Function(t.Object(t.prop('path',t.str),t.propOpt('encoding',t.str)),t.Object(t.prop('content',t.str),t.prop('size',t.num))).options({title:'Read file content',description:'Reads a file and returns its content and size'}),async({path:filePath, encoding='utf8'})=>{constcontent=fs.readFileSync(filePath,encoding);return{        content,size:content.length};}).prop('file.write',t.Function(t.Object(t.prop('path',t.str),t.prop('content',t.str),t.propOpt('encoding',t.str)),t.Object(t.prop('success',t.bool),t.prop('bytesWritten',t.num))).options({title:'Write file content',description:'Writes content to a file'}),async({path:filePath, content, encoding='utf8'})=>{fs.writeFileSync(filePath,content,encoding);return{success:true,bytesWritten:Buffer.from(content,encoding).length};}).prop('file.list',t.Function(t.Object(t.prop('directory',t.str),t.propOpt('pattern',t.str)),t.Object(t.prop('files',t.Array(t.str)),t.prop('count',t.num))).options({title:'List directory files',description:'Lists files in a directory, optionally filtered by pattern'}),async({ directory, pattern})=>{letfiles=fs.readdirSync(directory);if(pattern){constregex=newRegExp(pattern);files=files.filter(file=>regex.test(file));}return{        files,count:files.length};});constcli=createCli({  router,version:'v1.0.0',cmd:'file-cli'});cli.run();

# Read a filefile-cli file.read --str/path=package.json --format=json4# Write content from STDINecho"Hello World"| file-cli file.write --str/path=output.txt --in/content# List JavaScript filesfile-cli file.list --str/directory=src --str/pattern='\\.js$' --out=/files# Chain operations: read -> transform -> writefile-cli file.read --str/path=input.json|   file-cli transform.data|   file-cli file.write --str/path=output.json --in/content --format=json:raw