> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coconut.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# nut events

> View activity events

# `nut events`

View activity events in your Coconut instance.

```bash theme={null}
nut events [command]
```

## Overview

Events track all activity in your Coconut instance, providing a detailed audit log of what's happening. This includes task creation and updates, skill actions, resource changes, knowledge updates, and more.

***

## `nut events list`

List recent activity events.

```bash theme={null}
nut events list [options]
```

**Options:**

* `--limit <n>` - Number of events to display (default: 20)
* `--kind <type>` - Filter by event kind
* `--json` - Output as JSON

**Event Kinds:**

* `proposal` / `task` - Task-related events
* `knowledge` - Knowledge base changes
* `agent` / `skill` - Skill activity
* `resource` - Resource generation or updates
* `context` - Context document changes
* `code` - Code changes and commits

**Examples:**

```bash theme={null}
# List recent events
nut events list

# Show more events
nut events list --limit 50
nut events list --limit 100

# Filter by event type
nut events list --kind proposal
nut events list --kind knowledge
nut events list --kind agent

# Output as JSON for processing
nut events list --json
nut events list --kind task --json
```

***

## Event Information

Each event typically includes:

* **Timestamp** - When the event occurred
* **Kind** - Type of event (task, skill, resource, etc.)
* **Action** - What happened (created, updated, deleted, etc.)
* **Actor** - Who or what triggered the event (user, skill, system)
* **Details** - Specific information about the event

***

## Use Cases

### Auditing Activity

```bash theme={null}
# See what's been happening recently
nut events list --limit 50

# Track task progress
nut events list --kind proposal
```

### Debugging

```bash theme={null}
# Check skill activity
nut events list --kind agent

# Review code changes
nut events list --kind code
```

### Reporting

```bash theme={null}
# Export activity data
nut events list --limit 1000 --json > activity-report.json

# Generate filtered reports
nut events list --kind knowledge --json > knowledge-changes.json
```

### Monitoring

```bash theme={null}
# Check recent resource generation
nut events list --kind resource

# Monitor knowledge base updates
nut events list --kind knowledge --limit 20
```

***

## Event Examples

### Task Events

```
[2024-02-03 14:30:22] TASK_CREATED
  Task: "Add user authentication"
  ID: cp-1234567890
  Actor: user@example.com

[2024-02-03 14:35:10] TASK_UPDATED
  Task: cp-1234567890
  Status: draft → in-progress
  Actor: skill-001
```

### Knowledge Events

```
[2024-02-03 15:00:45] KNOWLEDGE_CREATED
  Document: "API Guidelines"
  Filename: api-guidelines.md
  Actor: user@example.com

[2024-02-03 15:30:12] KNOWLEDGE_UPDATED
  Document: api-guidelines.md
  Changes: Content updated
  Actor: user@example.com
```

### Skill Events

```
[2024-02-03 16:00:00] SKILL_ACTION
  Skill: "Code Reviewer"
  Task: cp-1234567890
  Action: Generated code review
  Actor: skill-002
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Regular monitoring">
    Periodically check events to stay aware of activity in your Coconut instance, especially in team environments.
  </Accordion>

  <Accordion title="Use filters effectively">
    When tracking specific types of activity, use `--kind` filters to reduce noise and focus on relevant events.
  </Accordion>

  <Accordion title="Export for analysis">
    Use `--json` output with tools like `jq` for detailed analysis and reporting of activity patterns.
  </Accordion>

  <Accordion title="Adjust limit based on needs">
    Start with default limits for quick checks, increase for comprehensive reviews or debugging.
  </Accordion>
</AccordionGroup>

***

## Combining with Other Commands

Events work well with other commands for comprehensive tracking:

```bash theme={null}
# See recent tasks and their events
nut task list
nut events list --kind proposal

# Check skill activity after creating one
nut skill create "Reviewer" "Reviews code"
nut events list --kind agent --limit 10

# Track knowledge changes
nut knowledge list
nut events list --kind knowledge
```

***

## JSON Output Format

When using `--json`, events are returned in a structured format suitable for programmatic processing:

```json theme={null}
{
  "events": [
    {
      "id": "evt-1234567890",
      "timestamp": "2024-02-03T14:30:22Z",
      "kind": "task",
      "action": "created",
      "actor": {
        "type": "user",
        "id": "user@example.com"
      },
      "data": {
        "taskId": "cp-1234567890",
        "title": "Add user authentication"
      }
    }
  ]
}
```

This enables integration with monitoring tools, analytics platforms, or custom scripts.