LaunchDarkly CLI dev-server reference guide

Overview

This guide describes all the functionality of the LaunchDarkly CLI dev-server. If you’re just getting started, you should read the guide to using the dev-server for local testing first.

LaunchDarkly provides a command line interface (CLI), which includes a dev-server command that you can use to start a local server and retrieve flag values from a LaunchDarkly source environment. This development server supports a single variation value for each flag, which you can override as needed. These flags and overrides are persisted in a SQLite database so that you can enjoy a local-only development experience after the initial sync of flags from the source environment. The dev-server supports low latency updates through streaming APIs just like the LaunchDarkly service, so you’ll be able to see flag changes in your application immediately.

When to use the dev-server

The dev-server is designed for local development, CI, and preview environments. Do not use it in production. If you want to use flags in unit tests, you should consider test data sources. If you need to set flags for a single server-side application, a simpler option is reading flags from files.

Prerequisites

If you’re just getting started with the dev-server, read the prerequisites section of the guide to using the dev-server for local testing to learn how to install and authenticate with the dev-server.

Starting the server

You can only start the server by using the CLI. To start the dev server, run the following command:

$
ldcli dev-server start

This will start the server. When the server starts, it will create a SQLite database file and log its location. The database file location is set based on the XDG state home. If you need to customize this location, you can set the XDG_STATE_HOME environment variable. If this is your first time starting the server, you’ll need to add a project before you can use the dev server to serve flags to your application.

Starting and syncing

You can programmatically sync flags from an environment before the dev-server starts. This can benefit workflows like continuous integration (CI) or ephemeral environments.

Here’s how to specify the source environment and project to sync while starting the dev-server:

$
ldcli dev-server start --project <project key> --source <environment key>

The dev-server will retrieve flag values from your project and environment before accepting connections.

You can also specify:

• The context to evaluate
• Local overrides

Here’s how you can specify the context and overrides on the command line:

$
ldcli dev-server start  --source staging --project default --context '{ "kind": "user", "key": "local-testing-key", "email": "ld-dev-server@launchdarkly.com"}' --override '{ "my-first-flag": true}'

If you’re using this in combination with some kind of persistent storage, you might not want to have the sync recur each time the server restarts. You can achieve this by setting the --sync-once option. When you set that, the sync will be skipped if a database file is already present.

You can view an example of using the dev-server with docker-compose at the LaunchDarkly Labs dev-server-docker-compose GitHub repo.

Project management

The dev-server creates an isolated, local environment for each of the LaunchDarkly projects that have been created within it. When projects are created in the dev-server, flags are “synced” to the dev-server from the source environment. The sync is performed by evaluating each flag from the source environment with a context. The resulting value is stored in the dev-server’s database.

Add project

Adding a project will create the project in the dev-server and sync all flags from the source environment by evaluating each flag with an optionally provided context.

$
ldcli dev-server add-project --project <project key> --source <environment key> --context <context>

Delete project

If you no longer need a project, you can remove it from the dev-server.

$
ldcli dev-server remove-project --project <project key>

Update project

If you want to use flag values from a different environment or context, you can update your project accordingly. For example, this is useful if you want to configure your flags to be exactly like what a customer saw in your production environment.

Here’s how:

$
ldcli dev-server update-project --project <project key> --source <source environment key> --context <JSON context> 

Sync project

You can resync flags from your source environment at any time. You’ll probably want to do this whenever you pull from your application’s code repository so that you have all the flags you need to run your application as your colleagues add flags. Syncing flags will use the previously configured source environment and context to evaluate each flag in the source environment for the context.

$
ldcli dev-server sync-project --project <project key>

Flag evaluation

The dev-server exposes APIs compatible with all supported LaunchDarkly SDKs on port 8765. These APIs enable connected SDKs to evaluate flags as if they were connected to the LaunchDarkly service. The dev-server does not support targeting: it always returns the same value for a flag. This value is fetched from the source environment, and it can be overridden. Flag overrides are a dev-server concept. They force the value of a flag in your dev-server instance to be a particular value. The overrides can be based on variations that exist in the LaunchDarkly service or they can be “local overrides.” Local overrides are variation values that only exist in your dev-server.

Add flag override

Create a flag override. This value will be returned instead of what has been synced from the source environment. Note that overrides persist between syncs.

$
ldcli dev-server add-override --project <project key> --flag <flag key> --data <flag value JSON>

Remove flag override

Remove a flag override. The flag will revert back to the value that was synced from the source environment.

$
ldcli dev-server remove-override --project <project key> --flag <flag key>

Back up and restore

The dev-server persists its flag and override state in a SQLite database. In a few cases, such as isolation testing or long-lived preview environments, you may want to back up and restore this state. The dev server includes an API that you may use to do this.

$
curl --output backup.db localhost:8765/dev/backup
>
curl --data-binary @backup.db http://localhost:8765/dev/backup

Dark mode

The dev-server UI supports a dark and light color scheme. It chooses the color scheme based on the color scheme preference indicated in your operating system.