npm package: @opes-app/cli
Description: Opes CLI - AI-powered financial assistant
Author: Opes Team
Latest version: 2.0.3

# @opes-app/cli

AI-powered financial CLI for the [Opes](https://github.com/opes-app/opes) platform. Manage your finances directly from the terminal.

## Features

- **AI Chat Interface** - Ask questions about your finances in natural language
- **Data Browser** - View accounts, transactions, categories, crypto wallets
- **Interactive Mode** - Full-featured terminal UI powered by OpenTUI
- **Settings** - Customize theme, colors, and preferences
- **Secure Authentication** - JWT-based login with secure credential storage

## Requirements

- [Bun](https://bun.sh) >= 1.0.0

## Installation

### Via Bun (recommended)

```bash
bun install -g @opes-app/cli
```

### Via standalone binary (no dependencies)

Download the latest binary for your platform from [GitHub Releases](https://github.com/opes-app/opes/releases):

```bash
# macOS (Apple Silicon)
curl -fsSL https://github.com/opes-app/opes/releases/latest/download/opes-darwin-arm64 -o opes
chmod +x opes
sudo mv opes /usr/local/bin/

# macOS (Intel)
curl -fsSL https://github.com/opes-app/opes/releases/latest/download/opes-darwin-x64 -o opes
chmod +x opes
sudo mv opes /usr/local/bin/

# Linux (x64)
curl -fsSL https://github.com/opes-app/opes/releases/latest/download/opes-linux-x64 -o opes
chmod +x opes
sudo mv opes /usr/local/bin/

# Linux (ARM64)
curl -fsSL https://github.com/opes-app/opes/releases/latest/download/opes-linux-arm64 -o opes
chmod +x opes
sudo mv opes /usr/local/bin/
```

## Usage

```bash
opes              # Start interactive mode
opes login        # Force browser re-authentication (device flow)
opes --local      # Connect to localhost:3001/v1 (development API)
opes --prod       # Connect to api.opes.app/v1 (production API)
opes --help       # Show help
```

## Navigation

| Key       | Action              |
| --------- | ------------------- |
| `Tab`     | Switch between tabs |
| `Up/Down` | Navigate list items |
| `Enter`   | Select / Confirm    |
| `Esc`     | Go back / Cancel    |
| `?`       | Show keyboard hints |

## Chat Commands

Use these commands inside the chat input:

| Command                        | Behavior                                                     |
| ------------------------------ | ------------------------------------------------------------ |
| `/new`                         | Start a new local chat session (server history is preserved) |
| `/history <query>`             | Search previous chat history in keyword mode                 |
| `/history --limit <n> <query>` | Same search with custom result limit (`1-20`)                |
| `/history --hybrid <query>`    | Deferred in CLI for now (embedding source prerequisite)      |

The assistant also applies balanced auto-retrieval for explicit memory-follow-up prompts and injects bounded snippets into context when triggered.

## Configuration

Settings are stored in `~/.opes/settings.json`:

- Theme (dark/light)
- Highlight color
- Default currency
- Date format
- Keyboard hints visibility

## Server Mode

The CLI can connect to either local development server or production:

```bash
# Use local server for this session
opes --local

# Use production server for this session
opes --prod
```

Default server mode is saved in settings and persists between sessions.

## Development

```bash
# Clone the repository
git clone https://github.com/opes-app/opes.git
cd opes/apps/cli

# Install dependencies
bun install

# Run in development mode
bun run dev

# Build
bun run build

# Run tests
bun test
```

## Migration from v1

If you're upgrading from CLI v1 (Ink-based):

1. CLI v2 requires [Bun](https://bun.sh) instead of Node.js
2. Or use standalone binaries (no runtime required)
3. Settings location remains `~/.opes/`
4. Authentication tokens are preserved

## License

MIT - see [LICENSE](https://github.com/opes-app/opes/blob/main/LICENSE) for details.

## Links

- [Opes Platform](https://github.com/opes-app/opes)
- [Issue Tracker](https://github.com/opes-app/opes/issues)
- [Changelog](https://github.com/opes-app/opes/blob/main/project/CHANGELOG.md)