# @cachly-dev/cli

> Official **cachly.dev** CLI – manage cache instances, brain lessons, and live data from your terminal.

[![npm](https://img.shields.io/npm/v/@cachly-dev/cli?color=red&logo=npm)](https://www.npmjs.com/package/@cachly-dev/cli)
[![npm downloads](https://img.shields.io/npm/dw/@cachly-dev/cli?color=blue&label=weekly%20installs)](https://www.npmjs.com/package/@cachly-dev/cli)
[![Free tier](https://img.shields.io/badge/Free%20tier-€0%2Fmo-brightgreen)](https://cachly.dev)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-yellow)](LICENSE)

> 🧠 **Looking for the AI Brain MCP server** (Claude Code, Cursor, Copilot, Windsurf)?  
> → [`@cachly-dev/mcp-server`](https://www.npmjs.com/package/@cachly-dev/mcp-server) · One-command setup: `npx @cachly-dev/mcp-server@latest autopilot`

---

## Installation

```bash
npm install -g @cachly-dev/cli
```

---

## Setup

```bash
# 1. Get your API token from https://cachly.dev/instances → Settings → API Token
# 2. Login:
cachly auth login --token <your-jwt>

# Or via environment variable (CI/CD):
export CACHLY_JWT=<your-jwt>
```

---

## Commands

### Auth
```bash
cachly auth login --token <jwt>   # Save token to ~/.cachly/config.json
cachly auth status                 # Show current auth + token info
cachly auth logout                 # Remove saved token
cachly auth token                  # Print JWT (for scripts)
```

### Instances
```bash
cachly instances list                               # List all instances
cachly instances get <id>                           # Get instance details
cachly instances create --name my-cache --tier free # Create new instance
cachly instances create --name prod-cache --tier pro
cachly instances delete <id> --yes                  # Delete (--yes to confirm)
cachly instances url <id>                           # Print Redis URL
```

**Tiers:** `free` · `dev` · `pro` · `speed` · `business`

### Cache Operations
```bash
cachly cache get   <instance-id> <key>            # Get value
cachly cache set   <instance-id> <key> <value>    # Set value
cachly cache set   <instance-id> <key> <value> --ttl 3600  # With TTL
cachly cache del   <instance-id> <key>            # Delete key
cachly cache keys  <instance-id>                  # List all keys
cachly cache keys  <instance-id> --pattern "user:*"  # Glob pattern
cachly cache ttl   <instance-id> <key>            # Check TTL
cachly cache stats <instance-id>                  # Memory, hit rate, ops/sec
cachly cache flush <instance-id> --yes            # Delete ALL keys (⚠️)
```

---

## Examples

```bash
# Onboarding a new user's cache instance
cachly instances create --name "llm-cache-prod" --tier pro

# Live testing a key
cachly cache set abc123 "greeting" "Hello, cachly!" --ttl 300
cachly cache get abc123 "greeting"
# → Hello, cachly!

# Monitor performance
cachly cache stats abc123
# → Memory: 12.4 MB | Hit Rate: 94.2% | Ops/sec: 342

# CI/CD script
REDIS_URL=$(cachly instances url $INSTANCE_ID)
echo "Connecting to $REDIS_URL"
```

---

## CI/CD Integration

```yaml
# GitHub Actions example
- name: Create cachly instance
  env:
    CACHLY_JWT: ${{ secrets.CACHLY_JWT }}
  run: |
    npx @cachly-dev/cli instances create --name "pr-${{ github.event.number }}" --tier dev
```

---

## Configuration

Config is stored in `~/.cachly/config.json`:
```json
{
  "jwt": "eyJhbGc...",
  "apiUrl": "https://api.cachly.dev"
}
```

Override via environment:
```bash
export CACHLY_API_URL=https://api.cachly.dev
export CACHLY_JWT=eyJhbGc...
```

---

## 👥 Team Brain — Shared AI Memory for Your Whole Team

One shared instance. Every developer gets smarter every day.

```bash
# .env — same instance for the whole team
export CACHLY_INSTANCE_ID=your-shared-team-instance

# Alice fixes a bug, stores the lesson:
cachly brain learn \
  --topic "deploy:k8s-timeout" \
  --outcome success \
  --what-worked "Increase readinessProbe.failureThreshold to 10" \
  --author alice

# Bob starts a session the next day:
cachly brain session-start
# → "💡 alice solved deploy:k8s-timeout 1d ago: Increase readinessProbe..."
```

Set up a team org at [cachly.dev/teams](https://cachly.dev/teams) — Team €99/mo · 10 seats · Business €299/mo · 50 seats.

---

## Development

```bash
cd sdk/cli
npm install
npm run build
node dist/index.js instances list   # test locally

# Link globally for testing:
npm link
cachly instances list
```