flora is a fast and secure runtime that lets you write discord bots for your servers, with a rich TypeScript SDK, without worrying about running infrastructure. [mirror]
docs: update pages a bit
+21
-96
+11
-25
apps/www/docs/cli.md
+11
-25
apps/www/docs/cli.md
···
4
4
5
5
# CLI
6
6
7
-
The Flora CLI manages deployments, logs, and KV stores against the runtime API.
8
-
9
-
## Install or run
10
-
11
-
From the repo root:
12
-
13
-
```bash
14
-
pnpm --filter @uwu/flora-cli run dev -- --help
15
-
```
7
+
:::info
8
+
Currently the CLI is unpublished. It will be published soon as `@uwu/flora-cli`.
9
+
:::
16
10
17
-
To build the local CLI:
18
-
19
-
```bash
20
-
pnpm --filter @uwu/flora-cli run build
21
-
```
11
+
The Flora CLI manages deployments, logs, and KV stores with the Flora Server API.
22
12
23
-
## Auth and config
13
+
## Login
24
14
25
-
- The CLI stores config in a per-user local config file.
26
-
- Set `FLORA_API_URL` or pass `--api-url` to point at your runtime.
27
-
- Authenticate once with a token:
15
+
Generate a API Token at https://app.flora.uwu.network/settings and then login with:
28
16
29
17
```bash
30
18
flora login <token>
···
34
22
35
23
### Deploy
36
24
37
-
Package a script and deploy to a guild:
25
+
To deploy to a guild:
38
26
39
27
```bash
40
-
flora deploy --guild 123456789012345678 path/to/main.ts
28
+
flora deploy
41
29
```
42
30
43
-
Deploy with an explicit root (what gets packaged):
44
-
45
-
```bash
46
-
flora deploy --guild 123456789012345678 path/to/main.ts --root path/to
47
-
```
31
+
- You can add `--guild [guildId]` to specify your guild (it prompts by default).
32
+
- A positional arg to specify a custom entrypoint script is also provided if needed.
33
+
- Using `--root path/to` allows you to specify a custom root (what gets packaged).
48
34
49
35
### Get
50
36
+3
-1
apps/www/docs/examples.md
+3
-1
apps/www/docs/examples.md
···
4
4
5
5
# Examples
6
6
7
-
This page covers the common flows end-to-end: prefix commands, slash commands,
7
+
This page covers the common flows like prefix commands, slash commands,
8
8
subcommands, embeds, KV usage, and deployment via the CLI.
9
9
10
10
## Minimal bot
···
168
168
flora kv get --guild 123456789012345678 --store notes welcome
169
169
flora kv list-keys --guild 123456789012345678 --store notes
170
170
```
171
+
172
+
See the [cli page](/docs/cli) for more info.
+2
-2
apps/www/docs/limitations.md
+2
-2
apps/www/docs/limitations.md
···
4
4
5
5
# Limitations
6
6
7
-
This page documents known limitations and design trade-offs in the flora runtime.
7
+
This page documents known limitations and design trade-offs you may face in flora's runtime.
8
8
9
9
## Cron Jobs
10
10
···
48
48
49
49
- **Exactly-once execution** with audit logs
50
50
- **Catch-up runs** after downtime
51
-
- **Non-idempotent side effects** (billing, one-time notifications)
51
+
- **Non-idempotent side effects** (webhooks, one-time notifications)
52
52
53
53
Consider implementing your own persistence layer using the [KV store](/docs/sdk#kv-store) to track execution state:
54
54
+1
-63
apps/www/docs/runtime.md
+1
-63
apps/www/docs/runtime.md
···
2
2
outline: deep
3
3
---
4
4
5
-
# Runtime
6
-
7
-
Flora Runtime is the Rust service that hosts Discord connectivity, V8 isolates,
8
-
and the HTTP API that the CLI uses. It bridges Discord events into a single
9
-
JavaScript runtime per guild and exposes Discord operations to scripts via ops.
10
-
11
-
## Architecture
12
-
13
-
Core components:
14
-
15
-
- Discord client (Serenity) for gateway events and REST calls
16
-
- Bot runtime for isolate lifecycle and event dispatch
17
-
- Deno Core ops for Discord actions, logging, KV, and command registration
18
-
- HTTP API for deployments, logs, KV, and token auth
19
-
- Storage: Postgres (deployments, tokens), Redis (sessions/cache), Sled (KV)
20
-
21
-
## Boot flow
22
-
23
-
At startup the runtime:
24
-
25
-
1. Loads config and initializes tracing.
26
-
2. Connects to Postgres and runs migrations.
27
-
3. Connects to Redis for cache/session storage.
28
-
4. Initializes V8 once per process.
29
-
5. Loads the SDK bundle into the runtime.
30
-
6. Restores cached deployments and starts the Discord client + HTTP server.
31
-
32
-
## Event flow
33
-
34
-
1. Discord gateway event arrives.
35
-
2. Event payload is serialized and routed to the guild isolate.
36
-
3. Handlers registered via `on()` execute.
37
-
4. Calls to `ctx.reply`, `ctx.edit`, `registerSlashCommands`, and `kv.*` map to
38
-
runtime ops and back to Discord or storage.
39
-
40
-
## KV store details
41
-
42
-
KV is scoped per guild and per store name. Stores are backed by Sled on disk
43
-
and indexed in Postgres. Runtime constraints:
44
-
45
-
- Value size max: 1 MB
46
-
- Key length max: 512 characters
47
-
- Store name max: 64 characters
48
-
- List default limit: 100, max 1000
49
-
- Optional metadata and expiration per key
50
-
- Prefix filtering and cursor-based pagination
51
-
52
-
## Configuration and services
53
-
54
-
Required:
55
-
56
-
- Discord bot token and OAuth client credentials
57
-
- Postgres for deployments and tokens
58
-
- Redis for cache and auth sessions
59
-
60
-
Optional:
61
-
62
-
- KV storage is always available, backed by local disk under `data/kv`
63
-
64
5
## Cron scheduler
65
6
66
7
The runtime includes a per-worker cron scheduler that fires every second to check for due jobs. Cron jobs registered via `cron()` in scripts are:
···
73
14
74
15
Cron jobs are cleared automatically when a guild script is redeployed or unloaded.
75
16
76
-
## Logs and metrics
77
-
78
-
The runtime exposes logs via the HTTP API and supports streaming logs via SSE,
79
-
which the CLI can follow in real time.
17
+
...document others later
+4
-5
apps/www/docs/sdk.md
+4
-5
apps/www/docs/sdk.md
···
249
249
250
250
- `skipIfRunning`: If `true`, the job won't start a new execution if the previous one is still running. Default: `false`.
251
251
252
-
Cron expressions follow standard 5-field format: `minute hour day-of-month month day-of-week`.
252
+
Cron expressions follow the usual standard 5-field format: `minute hour day-of-month month day-of-week`.
253
253
254
254
Limits:
255
255
256
-
- Max cron jobs per guild: 32 (configurable via `max_cron_jobs`)
257
-
- Handler timeout: 5 seconds (configurable via `cron_timeout_secs`)
256
+
- Max cron jobs per guild: 32
257
+
- Handler timeout: 5 seconds
258
258
259
259
## Utilities
260
260
···
269
269
270
270
## Types
271
271
272
-
Types are generated from the Rust runtime and available in the SDK. Use these
273
-
when authoring bot scripts and tests outside of the runtime bundle.
272
+
Types are automatically generated from the runtime structs using https://github.com/taskylizard/t0x. They are available in the `@uwu/flora-sdk` package, and also globally.