repartee 0.4.0

A modern terminal IRC client built with Ratatui and Tokio
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

---
category: Scripts
description: Manage user scripts
---

# /script

## Syntax

    /script [list|load|unload|reload|autoload|template] [name]

## Description

Manage user scripts. Scripts are Lua 5.4 files in `~/.repartee/scripts/`
that extend Repartee with custom commands, event hooks, filters, and automation.

Scripts run in a sandboxed Lua environment — `os`, `io`, `loadfile`, `dofile`,
and `package` are removed. Each script gets its own isolated environment.

## Subcommands

### list

Show currently loaded scripts with version and description.

    /script list

This is the default when no subcommand is given.

### load

Load a script by name.

    /script load <name>

Looks for `~/.repartee/scripts/<name>.lua`.

### unload

Unload a script. All event handlers, commands, and timers registered by
the script are automatically cleaned up. If the script returned a cleanup
function from `setup()`, it is called.

    /script unload <name>

### reload

Unload and reload a script.

    /script reload <name>

### autoload

Show or manage scripts that load automatically on startup.

    /script autoload

### template

Create a starter script file with the standard boilerplate.

    /script template

## Autoloading

All `.lua` files in `~/.repartee/scripts/` are loaded automatically on startup.

You can also explicitly list scripts in `config.toml`:

```toml
[scripts]
autoload = ["auto-away", "spam-filter"]
debug = false
```

## Writing Scripts

Scripts are `.lua` files with a `meta` table and a `setup` function:

```lua
meta = {
    name = "my-script",
    version = "1.0",
    description = "What it does",
}

function setup(api)
    -- Register event handlers
    api.on("irc.privmsg", function(ev)
        -- handle message
    end)

    -- Register custom commands
    api.command("mycommand", {
        handler = function(args, conn_id) --[[ ... ]] end,
        description = "Does something",
        usage = "/mycommand <arg>",
    })

    -- Optional: return cleanup function
    return function()
        api.log("my-script unloaded")
    end
end
```

### Available Events

**IRC events:** `irc.privmsg`, `irc.action`, `irc.notice`, `irc.join`, `irc.part`,
`irc.quit`, `irc.kick`, `irc.nick`, `irc.topic`, `irc.mode`, `irc.invite`,
`irc.ctcp_request`, `irc.ctcp_response`, `irc.wallops`

**Lifecycle events:** `command_input`, `connected`, `disconnected`

### Event Priority

Handlers run in descending priority order. Use priority constants:

- `api.PRIORITY_HIGHEST` (100)
- `api.PRIORITY_HIGH` (75)
- `api.PRIORITY_NORMAL` (50) — default
- `api.PRIORITY_LOW` (25)
- `api.PRIORITY_LOWEST` (0)

Return `true` from a handler to suppress the event.

### Per-Script Config

Access per-script config values at runtime:

```lua
local val = api.config.get("timeout", 300)
api.config.set("timeout", 600)
```

Read app-level config with dot-path notation:

```lua
local theme = api.config.app_get("general.theme")
```

## Examples

    /script list
    /script load auto-away
    /script reload auto-away
    /script unload auto-away
    /script template

## See Also

/set