description	flagd cheat sheet - quick reference for common operations

Cheat sheet

This cheat sheet provides quick reference examples for running flagd and evaluating flags using various protocols and configurations.

Recommended tools:

docker
curl
grpcurl
jq (optional, for formatting)

!!! tip

These commands assume a unix-like shell.

Output is generally JSON, and can be pretty-printed by piping into `jq` (ie: `curl ... | jq`)

Sample Flag Definitions

The examples below use these sample flag definition files. Download them to follow along:

cheat-sheet-flags.json - General application flags (flagSetId: app-flags)
cheat-sheet-flags-payments.json - Payment-related flags (flagSetId: payment-flags)

The app-flags set includes:

Flag Key	Type	Description
`simple-boolean`	boolean	Static boolean flag
`simple-string`	string	Static string flag
`simple-number`	integer	Static numeric flag
`simple-object`	object	Static object flag
`user-tier-flag`	string	Context-sensitive flag based on `tier`
`email-based-feature`	boolean	Context-sensitive flag based on `email` domain
`region-config`	object	Context-sensitive flag based on `region`

The payment-flags set includes:

Flag Key	Type	Description
`payment-provider`	string	Static payment provider selection
`max-transaction-amount`	integer	Context-sensitive based on `account-verified`
`enable-crypto-payments`	boolean	Context-sensitive based on `country`

Running flagd

=== "Docker"

```shell
# Single flag source (local file)
docker run --rm -it \
  -p 8013:8013 \
  -p 8015:8015 \
  -p 8016:8016 \
  -v $(pwd):/flags \
  ghcr.io/open-feature/flagd:latest start \
  --uri file:./flags/cheat-sheet-flags.json
```

```shell
# Multiple flag sources
docker run --rm -it \
  -p 8013:8013 \
  -p 8015:8015 \
  -p 8016:8016 \
  -v $(pwd):/flags \
  ghcr.io/open-feature/flagd:latest start \
  --uri file:./flags/cheat-sheet-flags.json \
  --uri file:./flags/cheat-sheet-flags-payments.json
```

```shell
# HTTP source
docker run --rm -it \
  -p 8013:8013 \
  -p 8015:8015 \
  -p 8016:8016 \
  -v $(pwd):/flags \
  ghcr.io/open-feature/flagd:latest start \
  --uri https://flagd.dev/assets/cheat-sheet-flags.json
```

=== "Binary"

```shell
# Single flag source (local file)
flagd start --uri file:./cheat-sheet-flags.json
```

```shell
# Multiple flag sources
flagd start \
  --uri file:./cheat-sheet-flags.json \
  --uri file:./cheat-sheet-flags-payments.json
```

```shell
# HTTP source
flagd start --uri https://flagd.dev/assets/cheat-sheet-flags.json
```

!!! note The remaining examples use Docker, but all CLI flags work identically with the binary.

OFREP API (HTTP)

The OFREP (OpenFeature Remote Evaluation Protocol) API is available on port 8016 by default.

Evaluate a Single Flag

curl -X POST 'http://localhost:8016/ofrep/v1/evaluate/flags/simple-boolean'

Response:

{
  "key": "simple-boolean",
  "reason": "STATIC",
  "variant": "on",
  "value": true,
  "metadata": {}
}

Evaluate Different Flag Types

# String flag
curl -X POST 'http://localhost:8016/ofrep/v1/evaluate/flags/simple-string'

# Number flag
curl -X POST 'http://localhost:8016/ofrep/v1/evaluate/flags/simple-number'

# Object flag
curl -X POST 'http://localhost:8016/ofrep/v1/evaluate/flags/simple-object'

Evaluate Multiple Flags (Bulk Evaluation)

curl -X POST 'http://localhost:8016/ofrep/v1/evaluate/flags'

Response:

{
  "flags": [
    {"key": "simple-boolean", "reason": "STATIC", "variant": "on", "value": true, "metadata": {}},
    {"key": "simple-string", "reason": "STATIC", "variant": "greeting", "value": "Hello, World!", "metadata": {}},
    {"key": "simple-number", "reason": "STATIC", "variant": "medium", "value": 50, "metadata": {}}
  ]
}

Context-Aware Evaluation

Context from Request Body

Pass evaluation context in the request body to trigger targeting rules:

# Evaluate with email context (triggers email-based-feature targeting)
curl -X POST 'http://localhost:8016/ofrep/v1/evaluate/flags/email-based-feature' \
  -H 'Content-Type: application/json' \
  -d '{"context": {"email": "user@example.com"}}'

Response (email matches @example.com):

{
  "key": "email-based-feature",
  "reason": "TARGETING_MATCH",
  "variant": "on",
  "value": true,
  "metadata": {}
}

# Evaluate with tier context
curl -X POST 'http://localhost:8016/ofrep/v1/evaluate/flags/user-tier-flag' \
  -H 'Content-Type: application/json' \
  -d '{"context": {"tier": "premium"}}'

# Bulk evaluation with multiple context values
curl -X POST 'http://localhost:8016/ofrep/v1/evaluate/flags' \
  -H 'Content-Type: application/json' \
  -d '{"context": {"email": "admin@example.com", "tier": "enterprise", "region": "us"}}'

Context from Static Values

Add static context values using the -X flag at startup. These are automatically included in all evaluations:

docker run --rm -it \
  -p 8013:8013 -p 8015:8015 -p 8016:8016 \
  -v $(pwd):/flags \
  ghcr.io/open-feature/flagd:latest start \
  --uri file:./flags/cheat-sheet-flags.json \
  -X region=eu \
  -X environment=production

# region=eu and environment=production is automatically applied without needing to send context
curl -X POST 'http://localhost:8016/ofrep/v1/evaluate/flags/region-config'

Context from HTTP Headers

Map HTTP headers to evaluation context keys using the -H flag at startup:

docker run --rm -it \
  -p 8013:8013 -p 8015:8015 -p 8016:8016 \
  -v $(pwd):/flags \
  ghcr.io/open-feature/flagd:latest start \
  --uri file:./flags/cheat-sheet-flags.json \
  -H "X-User-Tier=tier" \
  -H "X-User-Email=email"

Now context is extracted from request headers:

# tier context comes from X-User-Tier header
curl -X POST 'http://localhost:8016/ofrep/v1/evaluate/flags/user-tier-flag' \
  -H 'X-User-Tier: enterprise'

# email context comes from X-User-Email header
curl -X POST 'http://localhost:8016/ofrep/v1/evaluate/flags/email-based-feature' \
  -H 'X-User-Email: developer@example.com'

Context Priority

When using multiple context sources, values are merged with this priority (highest to lowest):

Header-mapped context values (-H flag)
Static context values (-X flag)
Request body context

Using the Selector Header

When using multiple flag sources, the Flagd-Selector header restricts which flags are evaluated.

Start flagd with multiple sources:

docker run --rm -it \
  -p 8013:8013 -p 8015:8015 -p 8016:8016 \
  -v $(pwd):/flags \
  ghcr.io/open-feature/flagd:latest start \
  --uri file:./flags/cheat-sheet-flags.json \
  --uri file:./flags/cheat-sheet-flags-payments.json

Filter evaluations by flag set (flagSetId):

# Evaluate only flags from the app flag set
curl -X POST 'http://localhost:8016/ofrep/v1/evaluate/flags' \
  -H 'Flagd-Selector: flagSetId=app-flags'

# Evaluate only flags from the payments flag set
curl -X POST 'http://localhost:8016/ofrep/v1/evaluate/flags' \
  -H 'Flagd-Selector: flagSetId=payment-flags'

# Single flag evaluation with selector
curl -X POST 'http://localhost:8016/ofrep/v1/evaluate/flags/payment-provider' \
  -H 'Flagd-Selector: flagSetId=payment-flags'

gRPC Evaluation API (evaluation.proto)

The gRPC evaluation service is available on port 8013 by default. Use grpcurl to interact with it.

!!! note "Proto files required" flagd does not support gRPC reflection. You must provide the proto files to grpcurl so it knows how to serialize/deserialize requests and responses. Clone the flagd repo or download the protos from buf.build/open-feature/flagd.

# Clone the repo for proto files
git clone git@github.com:open-feature/flagd-schemas.git
PROTO_DIR="flagd-schemas/protobuf/"

Evaluate Flags by Type

# Boolean flag
grpcurl -plaintext \
  -import-path "$PROTO_DIR" -proto flagd/evaluation/v2/evaluation.proto \
  -d '{"flagKey": "simple-boolean", "context": {}}' \
  localhost:8013 \
  flagd.evaluation.v2.Service/ResolveBoolean

# String flag
grpcurl -plaintext \
  -import-path "$PROTO_DIR" -proto flagd/evaluation/v2/evaluation.proto \
  -d '{"flagKey": "simple-string", "context": {}}' \
  localhost:8013 \
  flagd.evaluation.v2.Service/ResolveString

# With context
grpcurl -plaintext \
  -import-path "$PROTO_DIR" -proto flagd/evaluation/v2/evaluation.proto \
  -d '{"flagKey": "user-tier-flag", "context": {"tier": "enterprise"}}' \
  localhost:8013 \
  flagd.evaluation.v2.Service/ResolveString

Evaluate All Flags

grpcurl -plaintext \
  -import-path "$PROTO_DIR" -proto flagd/evaluation/v1/evaluation.proto \
  -d '{"context": {}}' \
  localhost:8013 \
  flagd.evaluation.v1.Service/ResolveAll

Using Selector Header

Filter which flags are evaluated using the Flagd-Selector header:

# Evaluate only flags from the app flag set
grpcurl -plaintext \
  -import-path "$PROTO_DIR" -proto flagd/evaluation/v2/evaluation.proto \
  -H 'Flagd-Selector: flagSetId=app-flags' \
  -d '{"flagKey": "simple-boolean", "context": {}}' \
  localhost:8013 \
  flagd.evaluation.v2.Service/ResolveBoolean

# ResolveAll with selector
grpcurl -plaintext \
  -import-path "$PROTO_DIR" -proto flagd/evaluation/v1/evaluation.proto \
  -H 'Flagd-Selector: flagSetId=payment-flags' \
  -d '{"context": {}}' \
  localhost:8013 \
  flagd.evaluation.v1.Service/ResolveAll

gRPC Sync API (sync.proto)

The gRPC sync service is available on port 8015 by default. This is used by in-process providers to fetch and sync flag configurations.

Use grpcurl to interact with it.

FetchAllFlags

Get all flag configurations as a single response:

grpcurl -plaintext \
  -import-path "$PROTO_DIR" -proto flagd/sync/v1/sync.proto \
  -d '{}' \
  localhost:8015 \
  flagd.sync.v1.FlagSyncService/FetchAllFlags

Response contains the complete flag configuration JSON:

{
  "flagConfiguration": "{\"flags\":{\"simple-boolean\":{...}}}"
}

FetchAllFlags with Selector

Filter which flag source's configuration is returned:

# Fetch only flags from cheat-sheet-flags.json
grpcurl -plaintext \
  -import-path "$PROTO_DIR" -proto flagd/sync/v1/sync.proto \
  -d '{"selector": "flagSetId=app-flags"}' \
  localhost:8015 \
  flagd.sync.v1.FlagSyncService/FetchAllFlags

# Fetch only payment flags
grpcurl -plaintext \
  -import-path "$PROTO_DIR" -proto flagd/sync/v1/sync.proto \
  -d '{"selector": "flagSetId=payment-flags"}' \
  localhost:8015 \
  flagd.sync.v1.FlagSyncService/FetchAllFlags

# With provider ID for identification
grpcurl -plaintext \
  -import-path "$PROTO_DIR" -proto flagd/sync/v1/sync.proto \
  -d '{"providerId": "my-app-sidecar", "selector": "flagSetId=app-flags"}' \
  localhost:8015 \
  flagd.sync.v1.FlagSyncService/FetchAllFlags

SyncFlags (Streaming)

Establish a server-streaming connection that pushes flag configuration updates in real-time:

grpcurl -plaintext \
  -import-path "$PROTO_DIR" -proto flagd/sync/v1/sync.proto \
  -d '{}' \
  localhost:8015 \
  flagd.sync.v1.FlagSyncService/SyncFlags

The stream outputs the initial flag configuration and continues streaming updates when flags change.

SyncFlags with Selector

# Stream only changes to app flags
grpcurl -plaintext \
  -import-path "$PROTO_DIR" -proto flagd/sync/v1/sync.proto \
  -d '{"selector": "flagSetId=app-flags"}' \
  localhost:8015 \
  flagd.sync.v1.FlagSyncService/SyncFlags

# Stream with provider ID
grpcurl -plaintext \
  -import-path "$PROTO_DIR" -proto flagd/sync/v1/sync.proto \
  -d '{"providerId": "my-service", "selector": "flagSetId=app-flags"}' \
  localhost:8015 \
  flagd.sync.v1.FlagSyncService/SyncFlags

Using Selector Header with Sync API

The Flagd-Selector header can be used as an alternative to the request body selector field:

grpcurl -plaintext \
  -import-path "$PROTO_DIR" -proto flagd/sync/v1/sync.proto \
  -H 'Flagd-Selector: flagSetId=app-flags' \
  -d '{}' \
  localhost:8015 \
  flagd.sync.v1.FlagSyncService/FetchAllFlags

If both header and request body contain a selector, the header takes precedence.

Quick Reference

Ports

Port	Protocol	Service	Description
8013	gRPC	Evaluation	Flag evaluation API (evaluation.proto)
8014	HTTP	Management	Health checks, metrics
8015	gRPC	Sync	Flag sync for in-process providers (sync.proto)
8016	HTTP	OFREP	OpenFeature Remote Evaluation Protocol

Health Check

curl http://localhost:8014/readyz

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cheat sheet

Sample Flag Definitions

Running flagd

OFREP API (HTTP)

Evaluate a Single Flag

Evaluate Different Flag Types

Evaluate Multiple Flags (Bulk Evaluation)

Context-Aware Evaluation

Context from Request Body

Context from Static Values

Context from HTTP Headers

Context Priority

Using the Selector Header

gRPC Evaluation API (evaluation.proto)

Evaluate Flags by Type

Evaluate All Flags

Using Selector Header

gRPC Sync API (sync.proto)

FetchAllFlags

FetchAllFlags with Selector

SyncFlags (Streaming)

SyncFlags with Selector

Using Selector Header with Sync API

Quick Reference

Ports

Health Check

See Also

FilesExpand file tree

cheat-sheet.md

Latest commit

History

cheat-sheet.md

File metadata and controls

Cheat sheet

Sample Flag Definitions

Running flagd

OFREP API (HTTP)

Evaluate a Single Flag

Evaluate Different Flag Types

Evaluate Multiple Flags (Bulk Evaluation)

Context-Aware Evaluation

Context from Request Body

Context from Static Values

Context from HTTP Headers

Context Priority

Using the Selector Header

gRPC Evaluation API (evaluation.proto)

Evaluate Flags by Type

Evaluate All Flags

Using Selector Header

gRPC Sync API (sync.proto)

FetchAllFlags

FetchAllFlags with Selector

SyncFlags (Streaming)

SyncFlags with Selector

Using Selector Header with Sync API

Quick Reference

Ports

Health Check

See Also