API reference
Client package
One Client per process. It owns the gateway, commands, cache, REST, and the
optional dashboard. Register commands and listeners, then run() or start().
Voice, runtime, REST.
Lifecycle
| Name |
Purpose |
run() |
Owns the loop and signals, then start(). Bad token: InvalidToken, exit 78. |
start() |
setup_hook(), services, metrics, then gateway or worker events until stop. Use this if you already have a loop. |
stop() |
Ask the loop to exit. Immediately refuse new dashboard connections. |
setup_hook() |
Async setup once per start. Do not call it yourself. |
Constructor
| Name |
Purpose |
token |
Bot token. Falls back to DISCORD_TOKEN. Required except worker role and public-key HTTP interactions. |
intents |
Gateway event mask. Default Intents.DEFAULT. Privileged bits also need the portal. |
primary_guilds |
Receive and store user server tags. Default True. |
prefix / command_prefix |
String, sequence, or callable. Mutually exclusive. |
case_insensitive |
Prefix command name matching. Default True. |
strip_after_prefix |
Drop whitespace between prefix and name. Default True. |
owners / owner_ids |
Owner ID collection. Mutually exclusive. |
max_messages |
Message cache size shortcut. Non-negative. Overrides that policy size. |
help_command |
Compatibility slot. Check the installed version. |
max_ratelimit_timeout |
Positive finite cap on REST rate-limit waits. |
sync_commands |
Overwrite application commands at ready. Default True. |
role |
monolith, gateway, or worker. Default "monolith". |
ipc |
Bus config for open_bus. Distributed roles need a shared transport. |
redis |
Pool or URL for bus/services/proxy. String → process-shared pool. Exposed as client.redis. |
cache_redis |
Cache pool or URL. Falls back to redis. |
dsn |
Database URL or Database. postgres://, sqlite://, mysql://. Falls back to DATABASE_URL / POSTGRES_URL. Exposed as client.db and client.postgres. |
rest_proxy |
Worker REST through proxy transport. Default False. |
metrics |
Collection and HTTP listener. Default True. |
metrics_host |
Default "127.0.0.1". ASTRAE_METRICS_HOST overrides. |
metrics_port |
Default 9100. ASTRAE_METRICS_PORT overrides. Cluster ID may offset. |
metrics_token |
Bearer for API/Prometheus. ASTRAE_METRICS_TOKEN overrides. |
loop_monitor |
Lag watchdog. Default True. Pass False or a LoopMonitor. |
gc_freeze |
Aggressive collect/freeze. Default True. False disables. GcFreezer() is freeze-only. |
late_event_seconds |
Late-dispatch threshold. Default 5.0. |
chunk_guilds_at_startup |
Member chunks at startup. Default False. |
cache_all_members_after_boot |
Redis member warmup. Needs member intent, Redis, unbounded user/member policies. |
member_warmup_concurrency |
Concurrent chunk requests. Default 1. |
member_warmup_interval |
Pause between requests. Default 1.0. |
member_warmup_memory_limit_mb |
RSS ceiling that pauses new chunks. ASTRAE_MEMBER_WARMUP_MEMORY_MB overrides. |
cache |
CacheConfig. Omitted means policy defaults. |
public_key |
Application public key for HTTP interactions without a gateway token. |
shards |
"recommended", explicit IDs, or None. |
allowed_mentions |
Default mention policy. Omitted means suppress mentions. |
status / activity |
Initial presence. |
State
| Name |
Purpose |
user |
Connected bot account (ClientUser) after READY. |
user.avatar |
Embed-safe asset (custom or default). |
user.banner |
Hydrated from GET /users/@me when READY omits it. USER_UPDATE refreshes it. |
application_id / user_id |
After identity is known. |
recommended_shards |
Discord's recommended shard count. |
running_shards / shard_states |
This process. |
latency |
Current heartbeat latency in milliseconds. |
avg_latency |
Mean across ready shards. Lives on Client, not user. |
lib / library |
"astrae". |
version |
Installed Astrae version. |
guild_count / server_count |
Fleet guild total after other clusters publish, else this process. len(guild_count) works. |
user_count / global_user_count |
Fleet member total. |
memory / memory_usage |
Fleet RSS in mebibytes. |
cpu |
Process CPU percent across all cores. |
command_count |
Registered commands and groups, excluding aliases, including nested commands. |
owners |
set[int]. |
prometheus |
Rendered exposition text. |
Lookups
| Name |
Purpose |
get_guild / get_channel / get_user / get_member / get_role / get_emoji |
Cache lookup. |
fetch_guild / fetch_channel / fetch_user / fetch_member / fetch_role / fetch_message / fetch_invite / fetch_webhook |
REST lookup. |
get_command / get_cog |
Registry lookup. |
in_guild |
Whether this process knows that guild. |
Methods
| Name |
Purpose |
set_presence |
Update gateway presence. |
once |
One-time listener. |
wait_for |
Await a matching event. Optional predicate/timeout. |
wait_for_message |
Await a matching message. Workers may use Redis. |
request_members |
Request guild member chunks. |
lock / unlock / hold |
Scheduler named locks. |
broadcast |
Worker/gateway control messages. |
remove_command / resync_commands |
Command registry. |
add_listener / remove_listener |
Event callbacks. |
load_extension / unload_extension / reload_extension |
Modules with setup(client). |
add_cog / add_plugin / add_view / add_loop |
Register groups, views, loops. |
setup_sentry / setup_tracelet |
Errors and activity to Sentry or Tracelet. SENTRY_DSN / TRACELET_DSN. Optional extra. |
setup_posthog |
command_used events. POSTHOG_API_KEY. Optional extra. |
Prefix and limits
| Name |
Purpose |
| Prefix callable |
Stored as prefix_for. Check the installed signature. |
case_insensitive |
Lowercases command-name comparison. Does not rewrite argument text. |
owner_only(*ids) |
Its own IDs. Does not read client.owners. |
| Constructor rejects |
Both prefix aliases, both owner aliases, non-positive warmup concurrency, negative interval, full warmup without GUILD_MEMBERS / Redis / unbounded user+member policies. |