@marteye/studio-cli/README.md

CLI for MartEye Studio API

# Studio CLI

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

## Installation

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

## Quick Start

### Initialize Configuration

```bash
studio config init
```

### Setup Tab Completion (Recommended)

```bash
# Automatic setup for your shell
studio completion setup

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

### Basic Usage

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
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:

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

### Manual Setup

If you prefer manual installation:

```bash
# 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:

```bash
studio completion uninstall
```

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

## Examples

### Create a Sale with Lots

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Install dependencies
yarn install

# Build the CLI
yarn build

# Run tests
yarn test

# Run in development mode
yarn dev
```

## License

MIT