Studio CLI

Command-line interface for MartEye Studio, built on top of the StudioJS SDK.

Installation

npm install -g @marteye/studio-cli
# or
yarn global add @marteye/studio-cli

Quick Start

Initialize Configuration

studio config init

Setup Tab Completion (Recommended)

# Automatic setup for your shell
studio completion setup

# Then restart your terminal or run:
source ~/.bashrc  # for bash
source ~/.zshrc   # for zsh

Basic Usage

# Get market details
studio market get greenfields

# List sales
studio sales list greenfields --start 2024-01-01 --end 2024-12-31

# Get lot details
studio lots get greenfields sale123 lot456

# Search for customers
studio search query greenfields "John Smith"

Configuration

The CLI stores configuration in ~/.studio/config.json. You can manage multiple profiles for different environments:

# Create a new profile
studio config create-profile staging

# Switch profiles
studio config use staging

# View current configuration
studio config list

Authentication

API keys can be provided in three ways (in order of precedence):

1. Command-line flag: --api-key YOUR_KEY
2. Environment variable: STUDIO_API_KEY
3. Configuration file: Set up with studio config init

Output Formats

The CLI supports multiple output formats:

• JSON (default): studio market get greenfields
• Table: studio market get greenfields -o table
• YAML: studio market get greenfields -o yaml
• CSV: studio lots list greenfields sale123 -o csv

Filtering Output

Use JMESPath queries to filter output:

# Get only lot IDs and prices for sold lots
studio lots list greenfields sale123 \
  --query "[?saleStatus=='Sold'].{id:id,price:unitPriceInCents}"

Global Options

• -k, --api-key <key> - API key for authentication
• -u, --base-url <url> - API base URL
• -t, --timeout <ms> - Request timeout in milliseconds
• -d, --debug - Enable debug mode
• -o, --output <format> - Output format: json, yaml, table, csv
• -q, --query <jmespath> - JMESPath query to filter output
• --profile <name> - Use a named configuration profile
• --no-color - Disable colored output
• -h, --help - Display help information
• -v, --version - Display version information

Available Commands

Market Operations

• studio market get <market-id> - Get market details

Sales Operations

• studio sales list <market-id> - List sales
• studio sales get <market-id> <sale-id> - Get sale details
• studio sales create <market-id> - Create new sale
• studio sales update <market-id> <sale-id> - Update sale

Lot Operations

• studio lots list <market-id> <sale-id> - List lots
• studio lots get <market-id> <sale-id> <lot-id> - Get lot details
• studio lots create <market-id> <sale-id> - Create new lot
• studio lots update <market-id> <sale-id> <lot-id> - Update lot
• studio lots delete <market-id> <sale-id> <lot-id> - Delete lot
• studio lots export <market-id> <sale-id> - Export lots

Customer Operations

• studio customers list <market-id> - List customers
• studio customers get <market-id> <customer-id> - Get customer details
• studio customers create <market-id> - Create new customer
• studio customers find-by-account <market-id> <account-number> - Find by account
• studio customers find-by-marteye <market-id> <marteye-uid> - Find by MartEye UID

Search Operations

• studio search query <market-id> <query> - Search within a market

Configuration

• studio config init - Initialize configuration
• studio config set <key> <value> - Set configuration value
• studio config get <key> - Get configuration value
• studio config list - List all configuration
• studio config use <profile> - Switch profile
• studio config create-profile <name> - Create new profile
• studio config delete-profile <name> - Delete profile

Utilities

• studio utils validate-eartag <tag> - Validate ear tag number

Shell Completion

• studio completion setup - Interactive setup of tab completion for your shell
• studio completion generate - Generate completion script for current shell
• studio completion uninstall - Remove tab completion from your shell

Tab Completion

The CLI includes built-in tab completion support for bash, zsh, and fish shells.

Automatic Setup

The easiest way to enable tab completion:

studio completion setup

This command will:

• Automatically detect your shell (bash/zsh/fish)
• Find the appropriate configuration file (.bashrc/.zshrc/config.fish)
• Ask for confirmation before making changes
• Create a backup of your configuration file
• Add the completion script

After setup, restart your terminal or run:

source ~/.bashrc  # for bash
source ~/.zshrc   # for zsh

Manual Setup

If you prefer manual installation:

# For bash
studio completion generate >> ~/.bashrc

# For zsh
studio completion generate >> ~/.zshrc

# For fish
studio completion generate >> ~/.config/fish/config.fish

What Gets Completed

Tab completion works for:

• All main commands (market, sales, lots, customers, etc.)
• Subcommands (e.g., studio sales <TAB> shows: list, get, create, update)
• Global options (--api-key, --format, --output, etc.)
• Format options (json, yaml, table, csv)

Uninstalling

To remove tab completion:

studio completion uninstall

This will cleanly remove the completion script from your shell configuration.

Examples

Create a Sale with Lots

# Create a new sale
studio sales create greenfields \
  --name "Weekly Cattle Sale" \
  --starts-at "2024-06-15T10:00:00Z" \
  --type LIVE

# Create lots in the sale
studio lots create greenfields sale123 \
  --lot-number "1001" \
  --product-code "CATTLE-01" \
  --price 150000 \
  --attributes '{"breed":"Angus","weight":450}'

Export Data

# Export lots to CSV file
studio lots export greenfields sale123 \
  --format csv \
  --output lots.csv

# Export filtered results
studio lots list greenfields sale123 \
  --status Sold \
  --query "[].{lot:lotNumber,price:unitPriceInCents}" \
  -o csv > sold-lots.csv

Working with Profiles

# Create profiles for different environments
studio config create-profile production
studio config create-profile staging

# Use staging profile for a command
studio --profile staging sales list marketA

# Set default profile
studio config use production

Development

# Install dependencies
yarn install

# Build the CLI
yarn build

# Run tests
yarn test

# Run in development mode
yarn dev

License

MIT