The Flora CLI provides a complete set of commands to manage key-value (KV) stores for your Discord bot. KV stores are guild-specific and allow you to persist data like user settings, preferences, and application state.
Store Management Create a Store Create a new KV store for a guild:
flora kv create-store --guild 123456789012345678 --name settings
Store names must be unique within a guild.
If --guild or --name are omitted, the CLI will prompt you interactively.
List Stores View all KV stores for a guild:
flora kv list-stores --guild 123456789012345678
Example output: KV stores for guild 123456789012345678: - settings - cache - user_data
Delete a Store Delete a KV store and all its data:
flora kv delete-store --guild 123456789012345678 --name settings
Deleting a store removes all keys and values permanently. This action cannot be undone.
Key-Value Operations Set a Value Store a value in a KV store:
flora kv set --guild 123456789012345678 --store settings --key prefix "!"
The value is provided as a positional argument after the flags.
Store JSON Data Store complex data as JSON:
flora kv set --guild 123456789012345678 --store settings --key config '{"prefix":"!","lang":"en"}'
Set with Expiration Set a value with an expiration timestamp (Unix epoch in seconds):
flora kv set --guild 123456789012345678 --store cache --key session "abc123" --expiration 1735689600
Expiration is specified as a Unix timestamp (seconds since epoch). Keys expire automatically after this time.
Attach metadata to a key:
flora kv set --guild 123456789012345678 --store settings --key session "xyz789" \ --expiration 1735689600 --metadata '{"source":"login","user_id":"456"}'
Get a Value Retrieve a value from a KV store:
flora kv get --guild 123456789012345678 --store settings prefix
The key is provided as a positional argument.
Example output: If the key doesn’t exist:
Delete a Value Remove a key-value pair:
flora kv delete --guild 123456789012345678 --store settings prefix
Example output: Deleted key 'prefix' from store 'settings' for guild 123456789012345678
List Keys List all keys in a store:
flora kv list-keys --guild 123456789012345678 --store settings
Example output: Keys in store 'settings' (3 shown): - prefix - lang - welcome_message
Filter by Prefix List only keys matching a prefix:
flora kv list-keys --guild 123456789012345678 --store user_data --prefix "user:"
This returns keys like user:123, user:456, etc.
Limit Results Limit the number of keys returned:
flora kv list-keys --guild 123456789012345678 --store settings --limit 10
If more keys are available, the output includes a cursor:
Keys in store 'settings' (100 shown): - key1 - key2 ... More keys available. Use --cursor eyJrZXkiOiJrZXkxMDAifQ==
Fetch the next page:
flora kv list-keys --guild 123456789012345678 --store settings --cursor eyJrZXkiOiJrZXkxMDAifQ==
Complete Examples User Preferences System Create Store
Set User Preference
Get User Preference
List All User Preferences
flora kv create-store --guild 123456789012345678 --name preferences
Session Management with Expiration Create Session Store
Create Session (1 hour)
Check Session
List Active Sessions
flora kv create-store --guild 123456789012345678 --name sessions
Bot Configuration Create Config Store
Set Prefix
Set Welcome Message
Set Moderator Role
View All Config
flora kv create-store --guild 123456789012345678 --name config
Key Naming Conventions Use structured key names for better organization:
# User data user: <user_id>:preference user: <user_id>:stats # Guild features feature: <feature_name>:enabled feature: <feature_name>:config # Temporary data session: <session_id> cache: <cache_key>
This makes it easy to:
List all keys for a specific entity using --prefix
Organize data logically
Clean up related keys efficiently
Data Types and Encoding KV stores accept string values. For complex data:
JSON Objects
Numbers as Strings
Boolean as String
Arrays
flora kv set --guild 123 --store data --key config '{"setting":"value"}'
Parse JSON values in your bot code using JSON.parse() after retrieving them.
Metadata provides additional context without affecting the stored value:
flora kv set --guild 123 --store data --key user_session "active" \ --metadata '{"created_by":"admin","version":2,"source":"web_login"}'
Metadata appears in list-keys output:
Keys in store 'data' (1 shown): - user_session [metadata: {"created_by":"admin","version":2,"source":"web_login"}]
Interactive Mode Omit required flags to enter interactive mode:
$ flora kv set ? Guild ID: 123456789012345678 ? Store name: settings ? Key: prefix ? Value: ! Set prefix=! in store 'settings' for guild 123456789012345678
Troubleshooting Store Not Found If you get a “store not found” error:
List available stores:
flora kv list-stores --guild 123456789012345678
Create the store if it doesn’t exist:
flora kv create-store --guild 123456789012345678 --name settings
Key Expiration If a key isn’t found but you expect it to exist, it may have expired. Check the expiration timestamp when listing keys.
Ensure metadata is valid JSON:
# Correct --metadata '{"key":"value"}' # Incorrect (missing quotes around value) --metadata '{key:value}'
Next Steps
Deploy Scripts Deploy a bot that uses KV stores
View Logs Debug KV operations in runtime logs