# Monitoring

The CableKnit CLI gives plugin developers visibility into what happens after install. View logs, track metrics, and investigate errors — all scoped to your publisher account.

## Privacy

All observability data is **publisher-scoped**. You see aggregate activity across all companies that have installed your plugin. Company identifiers are never exposed — the platform stores them internally for aggregation but never includes them in API responses or CLI output.

## Logs

View a chronological stream of events for your plugin:

```bash
cableknit logs <plugin-slug>
```

### Flags

| Flag | Description |
|------|-------------|
| `--type` | Filter by event type (e.g. `sandbox_execution`, `automation_failed`) |
| `--severity` | Filter by severity: `info`, `warning`, `error` |
| `--since` | Show logs since a timestamp (ISO 8601) |
| `--limit` | Max results (default 50, max 200) |
| `--json` | Output structured JSON |

### Example

```bash
cableknit logs my-plugin --severity error --limit 10
```

```
TIME                 TYPE                   SEVERITY   DETAIL
2026-03-24 14:23:01  sandbox_error          error      tool=execute_my_plugin_code error=Timeout after 5s
2026-03-24 13:45:12  automation_failed      error      automation=daily-sync error=API rate limit exceeded
```

## Metrics

View an aggregated metrics dashboard for your plugin:

```bash
cableknit metrics <plugin-slug>
```

### Flags

| Flag | Description |
|------|-------------|
| `--json` | Output structured JSON |

### Example output

```
Metrics — my-plugin

TOOL CALLS
  24h:  87
  7d:   543
  30d:  2104

ERRORS
  24h:        3
  Rate (7d):  1.24%

AUTOMATIONS
  Runs (7d):      28
  Failures (7d):  2

SANDBOX
  Avg Duration:  156.3 ms

INSTALLS
  Active:  14
```

## Errors

View only error-level events (convenience shortcut for `logs --severity error`):

```bash
cableknit errors <plugin-slug>
```

### Flags

| Flag | Description |
|------|-------------|
| `--since` | Show errors since a timestamp (ISO 8601) |
| `--limit` | Max results (default 25, max 100) |
| `--json` | Output structured JSON |

## Event types

| Event Type | Severity | Description |
|-----------|----------|-------------|
| `sandbox_execution` | info | Sandbox code executed successfully |
| `sandbox_error` | error | Sandbox code failed (timeout, memory, runtime error) |
| `tool_call` | info | Platform tool invoked |
| `tool_error` | error | Platform tool call failed |
| `automation_started` | info | Automation run began |
| `automation_completed` | info | Automation run finished successfully |
| `automation_failed` | error | Automation run failed |
| `decision_created` | info | Decision created during automation |
| `bundle_pushed` | info | New bundle version pushed |
| `bundle_validation_failed` | warning | Bundle validation failed during push |
| `bundle_rollback` | info | Plugin rolled back to a previous version |

## Log retention

Logs are retained for **90 days**. Older records are automatically cleaned up daily.

## Interactive shell

All three commands are also available in the interactive TUI shell under the **Monitor** section. Launch the shell with:

```bash
cableknit
```

Navigate to Monitor and select Logs, Metrics, or Errors.