Files
skillshare/website/docs/reference/commands/log.md
T
Willie 5f1521c3fd feat(log): comprehensive log improvements — partial status, instrumentation, retention, stats
- Report "partial" status for sync/install/update/uninstall when some
  items succeed and others fail
- Instrument 6 new commands: check, diff, trash, init, upgrade, and
  all mutating commands now log to operations.log
- Auto-truncation via WriteWithLimit with configurable log.max_entries
  (default 1000) and 20% hysteresis to avoid truncating every write
- Stats engine: computeLogStats with per-command breakdown
- CLI --stats flag with colored output and ✓ok/total ratios
- TUI stats panel (toggle with 's'): bar charts, status distribution,
  last operation timestamp
- TUI stats footer: compact always-visible summary line
- TUI detail panel: j/k scrolling for long entries, proportional
  list/detail layout (40%/60%)
- Web API: GET /api/log/stats endpoint
- Updated website docs for log command
2026-02-26 22:27:23 +08:00

8.5 KiB

sidebar_position
sidebar_position
4

log

View persistent operations and audit logs for debugging and compliance.

skillshare log                    # Interactive TUI (default on TTY)
skillshare log --audit            # Show only audit log
skillshare log --tail 50          # Show last 50 entries
skillshare log --cmd sync         # Show only sync entries
skillshare log --status error     # Show only errors
skillshare log --since 2d         # Entries from last 2 days
skillshare log --stats            # Show summary statistics
skillshare log --json             # Output as JSONL
skillshare log --no-tui           # Plain text output
skillshare log --clear            # Clear operations log
skillshare log -p                 # Project operations + audit logs

When to Use

  • Browse and filter log entries interactively
  • Debug what happened during a failed operation
  • Review the audit trail for compliance or troubleshooting
  • Filter logs by command, status, or time range for investigation

Interactive TUI

On a TTY, skillshare log launches an interactive terminal UI with:

  • Fuzzy filtering — type to filter by timestamp, command, status, source, or detail content
  • Keyboard navigation — arrow keys to browse, q to quit
  • Detail panel — shows full timestamp, command, status, duration, source, and structured args for the selected entry
  • Stats footer — always-visible compact summary: ops count, success rate, last operation
  • Stats panel — press s to toggle a full breakdown by command with success/failure counts
  • Merged view — operations and audit entries are merged and sorted by time when viewing both

Use --no-tui to skip the TUI and print plain text instead:

skillshare log --no-tui           # Plain text output
skillshare log --no-tui | less    # Pipe to pager manually

What Gets Logged

Every mutating CLI and Web UI operation is recorded as a JSONL entry with timestamp, command, status, duration, and contextual args.

Command Log File
install, uninstall, sync, push, pull, collect, backup, restore, update, target, trash, config, check, diff, init, upgrade operations.log
audit audit.log

Web UI actions that call these APIs are logged the same way as CLI operations.

Log Types

Default View

Shows both sections in one output:

  • Operations log
  • Audit log
skillshare log

Audit-Only View

Records security audit scans separately from normal operations.

skillshare log --audit

Filtering

Narrow results by command, status, or time range. When --cmd targets a specific log (e.g. --cmd audit only appears in audit.log), the irrelevant section is automatically skipped.

skillshare log --cmd install              # Only install entries
skillshare log --status error             # Only errors
skillshare log --since 1h                 # Last hour (also: 30m, 2d, 1w)
skillshare log --since 2026-01-15         # Since a specific date
skillshare log --cmd sync --status error  # Combine filters

JSON Output

Output raw JSONL for scripting and automation:

skillshare log --json                     # All entries as JSONL
skillshare log --json --cmd sync          # Filtered JSONL

Example Output (Plain Text)

When using --no-tui or in a non-TTY environment:

┌─ skillshare log ────────────────────────────────────┐
│ Operations (last 2)                                 │
│ mode: global                                        │
│ file: ~/.local/state/skillshare/logs/operations.log │
└─────────────────────────────────────────────────────┘
  TIME             | CMD       | STATUS  | DUR
  -----------------+-----------+---------+--------
  2026-02-10 14:31 | SYNC      | error   | 0.8s
  targets: 3
  failed: 1
  scope: global

  2026-02-10 14:35 | SYNC      | ok      | 0.3s
  targets: 3
  scope: global

┌─ skillshare log ────────────────────────────────────┐
│ Audit (last 1)                                      │
│ mode: global                                        │
│ file: ~/.local/state/skillshare/logs/audit.log      │
└─────────────────────────────────────────────────────┘
  TIME             | CMD       | STATUS  | DUR
  -----------------+-----------+---------+--------
  2026-02-10 14:36 | AUDIT     | blocked | 1.1s
  scope: all-skills
  scanned: 12
  passed: 11
  failed: 1
  failed skills:
    - prompt-injection-skill
    - data-exfil-skill

Log Format

Entries are stored in JSONL format (one JSON object per line):

{"ts":"2026-02-10T14:30:00Z","cmd":"install","args":{"source":"anthropics/skills/pdf"},"status":"ok","ms":1200}
Field Description
ts ISO 8601 timestamp
cmd Command name
args Command-specific context (source, name, target, etc.)
status ok, error, partial, or blocked
msg Error message (when status is not ok)
ms Duration in milliseconds

Log Location

~/.local/state/skillshare/logs/operations.log    # Global operations
~/.local/state/skillshare/logs/audit.log         # Global audit
<project>/.skillshare/logs/operations.log   # Project operations
<project>/.skillshare/logs/audit.log        # Project audit

Track Logs In Git (Project Mode)

Project mode ignores .skillshare/logs/ by default to avoid noisy commits.

If your team wants to version log files, add these user override rules in .skillshare/.gitignore after the managed block:

# User override: track logs
!logs/
!logs/*.log

If your repository root .gitignore also ignores .skillshare/, add matching unignore rules there as well.

Options

Flag Description
-a, --audit Show only audit log
-t, --tail <N> Show last N entries (default: 20)
--cmd <name> Filter by command name (e.g. sync, install, audit)
--status <status> Filter by status (ok, error, partial, blocked)
--since <dur|date> Filter by time (30m, 2h, 2d, 1w, or 2006-01-02)
--stats Show summary statistics (total, success rate, per-command breakdown)
--json Output raw JSONL (one JSON object per line)
--no-tui Disable interactive TUI, use plain text output
-c, --clear Clear selected log file (operations by default, audit with --audit)
-p, --project Use project-level log
-g, --global Use global log
-h, --help Show help

Web UI

The log is also available in the web dashboard at /log:

skillshare ui
# Navigate to Log page

The Log page provides:

  • Tabs for All, Operations, and Audit
  • Filters for command, status, and time range (1h, 24h, 7d, 30d)
  • Table view with time, command, details, status, and duration
  • Audit detail rows showing failed/warning skill names when present
  • Clear and Refresh controls

Stats View

CLI

skillshare log --stats                # Summary of all operations
skillshare log --stats --cmd sync     # Stats for sync only
skillshare log --stats --since 7d     # Stats for last 7 days

TUI

Press s in the TUI to toggle the stats panel, showing:

  • Total operations and per-command breakdown with horizontal bar chart
  • Success/failure counts per command (color-coded)
  • Overall success rate with visual progress bar
  • Last operation timestamp

The footer bar always shows a compact summary: 20 ops | ✓ 92.3% | last: sync 2h ago

Detail Panel Scrolling

When a log entry has long detail content (e.g. audit results with many skills), use j/k to scroll the detail panel up and down.

Log Retention

Logs are automatically truncated to prevent unbounded growth. The default limit is 1000 entries per log file (each CLI or Web UI operation = 1 entry). operations.log and audit.log are tracked separately.

To override the default, add to config.yaml:

log:
  max_entries: 500  # entries per file; 0 = unlimited (default: 1000)

See Also

  • audit — Security scanning (logged to audit.log)
  • status — Show current sync state
  • doctor — Diagnose setup issues