Feature Flags

A feature flag is a named, typed value. You read it and decide what to do with it.

if (await cloud.flags.isEnabled("new-hud")) {
  showNewHud();
}

const maxPlayers = await cloud.flags.getNumber("max-players", 32);

How reads work

Reading a flag serves the configuration from memory when it was fetched within the cache window, and goes to the API otherwise — so a read is usually free, and never more than one request per window no matter how often you call it.

The SDK does not poll in the background. The refresh happens on the read that finds the cache stale, and concurrent reads on a cold cache collapse onto a single request.

Configure the window when you construct the client:

const cloud = new NoCloud({
  apiKey: "your-api-key",
  flagsCacheTtlSeconds: 30 // default: 10
});

If a refresh fails while a previous configuration is held, that configuration is returned rather than throwing — an API blip must never change the values a running server reads. The cache window restarts in that case too, so an outage costs one request per window instead of one per read.

Reading values

Typed readers

Each reader checks the flag’s declared type as well as its value, so asking for a number and getting a string is impossible.

const enabled = await cloud.flags.getBoolean("new-hud", false);
const motd = await cloud.flags.getString("motd", "Welcome");
const maxPlayers = await cloud.flags.getNumber("max-players", 32);
const economy = await cloud.flags.getJson<EconomyConfig>("economy");

Without a fallback the return type is T | undefined; with one it is T.

A flag that does not exist — or that holds a different type than you asked for, or that this runtime may not read — reads as the fallback, or undefined when you did not pass one. Archiving or deleting a flag in the dashboard can never throw on a running server.

isEnabled

The shorthand for boolean flags. Defaults to false rather than undefined.

if (await cloud.flags.isEnabled("new-hud")) {
  showNewHud();
}

// With an explicit fallback
if (await cloud.flags.isEnabled("maintenance-mode", true)) {
  showMaintenanceScreen();
}

Raw and bulk reads

// Raw value, whatever the type
const value = await cloud.flags.getValue("max-players");

// A flag whole: key, type, value and runtime
const flag = await cloud.flags.getFlag("max-players");

// Every readable flag, whole
const flags = await cloud.flags.getFlags();

// Every readable flag as a plain key/value object
const all = await cloud.flags.getAll();
// { "new-hud": true, "motd": "Welcome", ... }

Runtimes

Reads are made on behalf of a runtime, and default to shared. A server flag is invisible to a shared read — it behaves exactly like a flag that does not exist — so a value you are about to send to a player can never be a server-only one by accident.

// Default: shared — a server-only flag reads as undefined
await cloud.flags.getString("webhook-url"); // undefined

// Say you are the server, and you see everything
await cloud.flags.getString("webhook-url", undefined, { runtime: "server" });
await cloud.flags.isEnabled("god-mode", false, { runtime: "server" });

// Exactly what is safe to relay to a player
const forClient = await cloud.flags.getAll(); // shared flags only

The runtime goes in the options object, which is always the last argument — after the fallback. Pass undefined as the fallback when you want a runtime but no fallback.

Configuration control

getConfig

Returns the flag configuration, from memory when it is still within the cache window and from the API otherwise. This is what every read calls under the hood.

const config = await cloud.flags.getConfig();

console.log(config.etag); // "a1b2c3d4e5f6a7b8"
console.log(config.generatedAt); // "2026-09-19T12:00:00.000Z"
console.log(config.pollIntervalSeconds); // 20
console.log(config.flags); // FlagConfigEntry[]

Returns

Promise<FlagConfigPayload>

Throws

NoCloudAPIError — only if the request fails and no configuration is held yet. When one is held, it is returned instead.

refresh

Fetches the configuration from the API, ignoring the cache window. Unlike getConfig this always surfaces a failure, so it is the right call when you want to know whether the API is reachable.

try {
  await cloud.flags.refresh();
} catch (error) {
  console.error("Flag API unreachable:", error);
}

Returns

Promise<FlagConfigPayload>

Throws

NoCloudAPIError — if the API request fails.

getCachedConfig

Returns the configuration currently held in memory without contacting the API. Synchronous.

const config = cloud.flags.getCachedConfig();

if (config === null) {
  console.log("Nothing fetched yet");
}

Returns

FlagConfigPayload | null

clearCache

Discards the cached configuration so the next read goes back to the API.

cloud.flags.clearCache();

The management methods (create, update, delete) call this for you, so a read straight after a write never serves the value you just replaced.

Driving your own refresh loop

pollIntervalSeconds on the payload is what the API advises. The SDK does not act on it, so use it if you want a loop of your own:

async function watchFlags() {
  for (;;) {
    const config = await cloud.flags.refresh();
    await new Promise((resolve) =>
      setTimeout(resolve, config.pollIntervalSeconds * 1000)
    );
  }
}

Managing flags

These methods hit the management endpoints directly and require FLAGS_WRITE (except list, get, getQuota and getAuditLog, which need only FLAGS_READ).

list

Lists the organization’s flags.

const { results, quota, total, page, totalPages } = await cloud.flags.list({
  page: 1,
  limit: 20,
  search: "hud",
  includeArchived: false
});

Parameters

options: ListFlagsOptions — page, limit, search, includeArchived (all optional)

Returns

Promise<FeatureFlagListResponse> — a page of flags plus your flag allowance

create

Creates a flag. The type and value are paired in TypeScript, so the compiler rejects a number flag holding a string.

const flag = await cloud.flags.create({
  key: "new-hud",
  name: "New HUD",
  description: "Rolls out the redesigned heads-up display",
  type: "boolean",
  value: true,
  runtime: "shared"
});

// A secret must be created as server-only
await cloud.flags.create({
  key: "webhook-url",
  name: "Alert webhook",
  type: "string",
  value: "https://discord.com/api/webhooks/...",
  runtime: "server"
});

Returns

Promise<FeatureFlag>

Throws

NoCloudAPIError — including when the organization is at its flag allowance, or the key is already taken.

get

Fetches a single flag by its ID.

const flag = await cloud.flags.get(flagId);

To read a flag’s value by key, use getValue and the typed readers — they serve from the cached configuration instead of making a request per flag.

Returns

Promise<FeatureFlag>

update

Renames, archives, or sets a flag’s value.

// Flip a boolean
await cloud.flags.update(flagId, { type: "boolean", value: false });

// Archive — servers stop seeing it, the key stays reserved
await cloud.flags.update(flagId, { archived: true });

// Close a flag to clients
await cloud.flags.update(flagId, { runtime: "server" });

// Rename
await cloud.flags.update(flagId, { name: "New HUD (beta)" });

Changing the value means passing its type alongside it. Keys are immutable and cannot be updated.

Returns

Promise<FeatureFlag>

Throws

NoCloudAPIError — including when the flag is locked by the organization’s allowance.

delete

Permanently deletes a flag.

await cloud.flags.delete(flagId);

Returns

Promise<void>

getQuota

Fetches the organization’s flag allowance.

const quota = await cloud.flags.getQuota();

console.log(`${quota.used} / ${quota.max} flags used`);

if (quota.locked > 0) {
  console.warn(`${quota.locked} flag(s) locked — subscribe to edit them`);
}

Returns

Promise<FeatureFlagQuota> — max, used, subscribed, locked

getAuditLog

Fetches the flag audit log — who changed what, and when.

const { results } = await cloud.flags.getAuditLog({
  page: 1,
  limit: 20,
  flagId // optional: one flag's history
});

for (const entry of results) {
  console.log(entry.createdAt, entry.actorType, entry.action, entry.flagKey);
}

Returns

Promise<PaginatedResult<FeatureFlagAuditEntry>> — newest first

Types

type FeatureFlagType = "boolean" | "string" | "number" | "json";
type FeatureFlagRuntime = "server" | "shared";

interface FlagConfigEntry {
  key: string;
  type: FeatureFlagType;
  value: JsonValue;
  runtime: FeatureFlagRuntime;
}

interface FlagConfigPayload {
  etag: string;
  generatedAt: string;
  pollIntervalSeconds: number;
  flags: FlagConfigEntry[];
}

interface FeatureFlag {
  id: string;
  key: string;
  name: string;
  description: string | null;
  type: FeatureFlagType;
  value: JsonValue;
  runtime: FeatureFlagRuntime;
  archived: boolean;
  locked: boolean;
  createdAt: string;
  updatedAt: string;
}

interface FeatureFlagQuota {
  max: number;
  used: number;
  subscribed: boolean;
  locked: number;
}

Next Steps

Feature Flags

Types, runtimes, limits and the audit log

Error Handling

Handle NoCloudAPIError gracefully

API Reference

The REST endpoints behind this module

CFX SDK

CFX NUI SDK

Node.js SDK

Feature Flags

How reads work

Reading values

Typed readers

isEnabled

Raw and bulk reads

Runtimes

Configuration control

Driving your own refresh loop

Managing flags

Types

Next Steps

Feature Flags

Error Handling

API Reference

​How reads work

​Reading values

​Typed readers

​isEnabled

​Raw and bulk reads

​Runtimes

​Configuration control

​Driving your own refresh loop

​Managing flags

​Types

​Next Steps

Feature Flags

Error Handling

API Reference

How reads work

Reading values

Typed readers

isEnabled

Raw and bulk reads

Runtimes

Configuration control

Driving your own refresh loop

Managing flags

Types

Next Steps