Muscula CLI

Command-line interface for Muscula error tracking. Authenticates via OAuth 2.1 + PKCE, lists projects and logs, reads error details, creates projects and logs, and prints integration instructions — all from the terminal.

Driving this from an AI agent? See AGENTS.md for a machine-facing guide (concepts, scriptable workflows, exit codes).

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

# Headless / SSH / container: print the URL and paste back the redirect URL or code
muscula login --manual

# 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); set MUSCULA_CLI_HOME to override that directory.

The default flow opens a browser and waits on a loopback callback (127.0.0.1:18923), which only works when the browser runs on the same machine. On a remote/headless host use muscula login --manual: open the printed URL in any browser, sign in, then copy the http://127.0.0.1:18923/callback?code=... address you get redirected to (it won't load — that's fine) and paste it back. Pasting just the code value works too.

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

muscula create-project <name>

Create a new project.

$ muscula create-project "Mobile Backend"

Project "Mobile Backend" created.  (64f0aa11bb22cc33dd44ee55)

muscula create-log <project-name> <name>

Create a new log (error source) inside a project. --type selects the framework and determines which integration snippet you get (default javascript).

$ muscula create-log "Mobile Backend" "Prod API" --type dotnet

Log "Prod API" created.  (qR7tY8, .NET Core (Microsoft.Extensions.Logging))

Accepted --type aliases: javascript (js), javascript_app (js-app), dotnet_core (dotnet), dotnet_log4net (log4net), java_log4j (log4j), java_logback (logback), php, wordpress (wp), uptime_check (uptime), node, angular, react.

For an uptime check, pass the URL to monitor with --url:

$ muscula create-log "My Web App" "Homepage uptime" --type uptime --url https://example.com

muscula uptime <add|set-url|events>

Manage uptime checks. An uptime check is just a log of type uptime with a URL to monitor, so uptime add is a friendlier shortcut for create-log --type uptime --url.

$ muscula uptime add "My Web App" "Homepage uptime" https://example.com

Uptime check "Homepage uptime" created.  (kmqt1Tw)
Monitoring: https://example.com

Change the monitored URL on an existing check (by id or name):

$ muscula uptime set-url "Homepage uptime" https://example.com/health

Updated "Homepage uptime".  Monitoring: https://example.com/health

Show the recorded uptime events (downtime history) for a check, newest first:

$ muscula uptime events "Homepage uptime"

Homepage uptime  [kmqt1Tw]  total: 2  page: 1/1
  Monitoring: https://example.com/health

  Time                  Status                Response
  ──────────────────────────────────────────────────────────────
  2026-06-10 07:01:32   OK
  2026-06-10 07:00:52   BadGateway            Bad Gateway

muscula integration <log>

Print copy-paste integration code for a log, by log id or name. The Log ID is already embedded.

$ muscula integration "Prod API"

Integration instructions for "Prod API" (.NET Core (Microsoft.Extensions.Logging))
============================================================

1. Install NuGet package:
   dotnet add package Muscula.Csharp.Extensions.Logging.AspNetCore
...

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) | | -t, --type <type> | create-log | Framework type (default: javascript) | | -u, --url <url> | create-log | URL to monitor (required for uptime_check logs) | | -e, --notify-email <email> | create-log, uptime add | Email for error/downtime notifications | | --no-notify-on-new | create-log, uptime add | Do not notify on new errors/downtime | | -p, --page <n> | uptime events | Page number (default: 1) | | -V, --version | | Show version | | -h, --help | | Show help for any command |

| 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