Overview flora consists of two main components:
Runtime - The Rust-based service that executes bot scripts using V8 isolatesCLI - The TypeScript command-line tool for deploying and managing bots
flora is in early alpha. Expect breaking changes and rough edges as the foundations solidify.
Installing the CLI The flora CLI is the primary tool for deploying scripts, viewing logs, and managing KV storage.
Using npm Install globally with npm:
npm install -g @uwu/flora-cli
Using the monorepo If you’re working from the flora repository:
# Install dependencies pnpm install # Build the CLI pnpm --filter @uwu/flora-cli run build # Run the CLI directly pnpm --filter @uwu/flora-cli run dev -- --help
Verify installation You should see the available commands:
Usage: flora [options] [command] Commands: login <token> Authenticate with the flora API deploy Deploy a bot script to a guild get Get deployment info for a guild list List all deployments health Check runtime health logs View or stream logs kv Manage KV storage
Setting up the Runtime The flora runtime is a Rust application that handles Discord gateway events and executes bot scripts in isolated V8 environments.
Prerequisites
Install Rust
Install the Rust toolchain: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Install system dependencies
Install required system packages: macOS: brew install postgresql redis
Ubuntu/Debian: sudo apt install postgresql redis-server libssl-dev pkg-config
Clone the repository
git clone https://github.com/uwu/flora.git cd flora
Building the Runtime flora uses both Cargo and Buck2 for building. The ./x wrapper scripts simplify common workflows.
Development build Build the runtime in debug mode:
This runs cargo build with the appropriate flags.
Release build Build an optimized release version:
This uses Buck2 to build the //apps/runtime:flora_bin_release target.
Development Environment flora needs PostgreSQL and Redis/Valkey to run:
This starts:
PostgreSQL on port 5433
Redis/Valkey on port 5434
The script prints the connection URLs:
DATABASE_URL = postgres://user:pass@localhost:5433/flora REDIS_URL = redis://localhost:5434
Copy these environment variables - you’ll need them to run the runtime.
Configuration Create a config.toml file in the root directory:
# Discord bot token discord_token = "YOUR_DISCORD_BOT_TOKEN" # Database connection database_url = "postgres://user:pass@localhost:5433/flora" # Redis connection redis_url = "redis://localhost:5434" # API server api_host = "127.0.0.1" api_port = 3000 # Runtime limits max_cron_jobs = 32 cron_timeout_secs = 5
Alternatively, use environment variables:
export DISCORD_TOKEN = "YOUR_DISCORD_BOT_TOKEN" export DATABASE_URL = "postgres://user:pass@localhost:5433/flora" export REDIS_URL = "redis://localhost:5434"
Never commit .env, config.toml, or testbotenv files to version control. These files contain sensitive credentials.
Running the Runtime Start the development runtime:
Or the release build:
The runtime will:
Connect to Discord using your bot token
Start the HTTP API server (default: http://localhost:3000)
Listen for Discord events
Execute bot scripts in V8 isolates per guild
Verify the runtime is running Check the health endpoint:
curl http://localhost:3000/health
Or use the CLI:
Installing the SDK The flora SDK provides TypeScript types and global namespace definitions for bot development.
For bot development Install as a dev dependency in your bot project:
npm install --save-dev @uwu/flora-sdk
Configure TypeScript to use the SDK types:
{ "compilerOptions" : { "lib" : [ "ESNext" , "DOM" ], "target" : "ESNext" , "module" : "Preserve" , "moduleResolution" : "bundler" , "moduleDetection" : "force" , "allowImportingTsExtensions" : true , "verbatimModuleSyntax" : true , "noEmit" : true , "strict" : true , "skipLibCheck" : true , "types" : [ "@uwu/flora-sdk" ] }, "include" : [ "src" ] }
For SDK development If you’re contributing to the SDK:
# Install dependencies pnpm install # Build the SDK pnpm --filter sdk run build # Run tests pnpm --filter sdk test # Type check pnpm --filter sdk run typecheck
Authenticating the CLI Connect the CLI to your runtime:
The CLI stores configuration in a local config file. You can also specify the API URL:
# Set via environment variable export FLORA_API_URL = http :// localhost : 3000 # Or pass with each command flora --api-url http://localhost:3000 health
Next steps Now that you have flora installed:
Quickstart Create your first bot in minutes
Runtime Configuration Learn about runtime configuration options
CLI Guide Master the flora CLI commands
SDK Overview Explore the SDK API
Common Build Commands Rust/Runtime # Build entire workspace cargo build # Build runtime (dev) ./x build-dev # Build runtime (release) ./x build-release # Run runtime (dev) ./x run-dev # Run runtime (release) ./x run-release # Run tests cargo test # Lint (must pass with zero warnings) cargo clippy --all-targets -- -D warnings # Format code cargo fmt
TypeScript/SDK # Install dependencies pnpm install # Build CLI pnpm --filter @uwu/flora-cli run build # Build SDK pnpm --filter sdk run build # Run SDK tests pnpm --filter sdk test # Format TypeScript/JSON/YAML/TOML/Markdown dprint fmt # Type check SDK pnpm --filter sdk run typecheck
Troubleshooting CLI not found after installation Make sure npm global bin directory is in your PATH:
npm config get prefix # Add <prefix>/bin to your PATH
Runtime fails to start Check that PostgreSQL and Redis are running:
Verify your configuration:
echo $DATABASE_URL echo $REDIS_URL echo $DISCORD_TOKEN
Type errors in bot script Ensure @uwu/flora-sdk is installed and tsconfig.json includes:
"types" : [ "@uwu/flora-sdk" ]
Buck2 build issues Sync Rust dependencies:
./x sync-rust-deps ./x buckify-rust-deps