Muscula CLI

Command-line interface for Muscula error tracking. Authenticates via OAuth 2.1 + PKCE, fetches projects, logs, and error details — all from the terminal.

Installation

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

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

Authentication

# 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

# 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