npm package: @muscula.com/muscula-cli
Description: Muscula.com CLI for error tracking and log inspection
Author: Michal Zubkowicz
Latest version: 0.1.2

# Muscula CLI

Command-line interface for [Muscula](https://www.muscula.com) error tracking. Authenticates via OAuth 2.1 + PKCE, fetches projects, logs, and error details — all from the terminal.

## Installation

```bash
npm install -g @muscula.com/muscula-cli
```

Requires Node.js 18+ or Bun. If Bun is installed, it will be used automatically.

## Authentication

```bash
# Login (opens browser for OAuth)
muscula login

# Login to a custom server
muscula login --server https://app.test.muscula.com

# Logout (remove stored tokens)
muscula logout
```

Tokens are stored in `~/.muscula-cli/config.json` (permissions `0600`).

## Commands

### `muscula projects`

List all projects with their logs and error counts.

```
$ muscula projects

My Web App  (64a1b2c3d4e5f6)
  ├─ Production  [xK9mN2]  errors: 42
  ├─ Staging     [pL3qR7]  errors: 5

Backend API  (64a1b2c3d4e5f7)
  ├─ API Errors  [tY8wZ1]  errors: 12
```

### `muscula logs <project-name>`

List all logs for a project with configuration details.

```
$ muscula logs "My Web App"

Logs for My Web App

ID            Name                          Type          Structural  API Key
──────────────────────────────────────────────────────────────────────────────────────
xK9mN2        Production                    WebApp        yes         abc123
pL3qR7        Staging                       WebApp        no          def456
```

### `muscula errors <project-name>`

List recent errors from all logs in a project.

```
$ muscula errors "My Web App"

Production  [xK9mN2]  total: 42  page: 1/3

  Severity  Count   Last seen              Message                                                     IDs
  ────────────────────────────────────────────────────────────────────────────────────────────────────────────
  Error     156 ↑   2025-01-15 14:23:01    TypeError: Cannot read property 'id' of undefined          xK9mN2/64abc...
  Warning   23  ↓   2025-01-15 12:01:45    Deprecated API endpoint called                             xK9mN2/64abd...
```

### `muscula errors --log <log-name>`

List errors from a specific log.

```
$ muscula errors --log Production
$ muscula errors --log Production --page 2
```

### `muscula error <log-id> <flat-id>`

Show full error details — message, stack trace, versions, page URLs, device info, and more.

```
$ muscula error xK9mN2 64abc123def456

Error Detail  xK9mN2/64abc123def456
════════════════════════════════════════════════════════════════════════════════

Message
───────
TypeError: Cannot read property 'id' of undefined

  Severity:        Error
  Count:           156
  First seen:      2025-01-10 09:15:32
  Last seen:       2025-01-15 14:23:01
  Location:        app.js:142:12
  Starred:         no
  Ignored:         no

Stack Trace
────────────────────────────────────────────────────────────────────────────────
  at UserService.getUser (app.js:142:12)
  at Router.handleRequest (router.js:89:5)
  at Server.listen (server.js:23:3)

Versions
────────────────────────────────
  2.1.0                    120
  2.0.9                    36

Page URLs
────────────────────────────────────────────────────────────────────────────────
  89       https://example.com/dashboard
  45       https://example.com/profile
  22       https://example.com/settings

Devices
────────────────────────────────────────────────────────────────────────────────
  67       Chrome 120 / Windows 10 / Desktop
  45       Safari 17 / macOS 14 / Desktop
  44       Chrome 120 / Android 14 / Mobile
```

## Options

| Flag | Command | Description |
|------|---------|-------------|
| `-s, --server <url>` | `login` | Server URL (default: `https://app.muscula.com`) |
| `-l, --log <name>` | `errors` | Filter errors by log name |
| `-p, --page <n>` | `errors` | Page number (default: `1`) |
| `-V, --version` | | Show version |
| `-h, --help` | | Show help for any command |

## Development

```bash
# Install dependencies
npm install

# Generate API client (requires running Muscula.App on localhost:5001)
npm run generate-api

# Build
npm run build

# Run locally
./bin/muscula projects
```

## Architecture

Clean architecture with 4 layers:

```
cli/ (presentation) → application/ (use cases) → domain/ (models + ports) ← infrastructure/ (adapters)
```

- **domain/** — business models and port interfaces (zero dependencies)
- **application/** — use cases orchestrating domain logic
- **infrastructure/** — API client, OAuth flow, file-based config storage
- **cli/** — commander.js commands and terminal formatters

## License

MIT