Define flags in code

Overview

Flag definitions live in TypeScript or Go, reviewed in pull requests like any other code. The CLI reads shipd.config.ts or shipd.config.go directly. In this guide you add a boolean flag and a variant flag, then create both with shipd push. Prerequisites

The shared @shipdit/cli installed (npm install -g @shipdit/cli), with Node.js 22.12+ to run it. TypeScript projects also install shipdit; Go definitions use github.com/alasti-company/useshipd.com/sdks/go/config; install the Go SDK when evaluating flags.
shipd login completed, or a service account token in SHIPD_API_KEY. See Push permissions.

Define the flags

For TypeScript, create shipd.config.ts in the project root. For Go, create shipd.config.go in your module. The CLI finds its config by walking up from the current directory.

// shipd.config.ts
import { defineFlags } from "shipdit/config";

export default defineFlags({
  "new-checkout": {
    type: "boolean",
    default: false,
    description: "Redesigned checkout flow",
    tags: ["checkout"],
  },
  "search-variant": {
    type: "variant",
    variants: ["control", "semantic", "hybrid"] as const,
    default: "control",
    description: "Search ranking experiment",
  },
});

// shipd.config.go
package main

import "github.com/alasti-company/useshipd.com/sdks/go/config"

var Config = config.ShipdConfig{
	"new-checkout": {Type: "boolean", Default: false,
		Description: "Redesigned checkout flow", Tags: []string{"checkout"}},
	"search-variant": {Type: "variant", Default: "control",
		Variants: []string{"control", "semantic", "hybrid"}},
}

The object key is the flag key your code reads.
default is what the environment you push to serves until you add rules.
In TypeScript, write variants with as const; invalid defaults fail type checking. Go validates defaults when you call Config.Validate, or Config.Defaults.

Number and JSON flags use the same shape. See Number and JSON flags.

Go definitions

Flag definitions use the config package, which ships with the Go SDK:

go get github.com/alasti-company/useshipd.com/sdks/go

The CLI reads shipd.config.go directly and generates Go accessors by default, unless typesLanguage overrides the output language. Define an exported var Config = config.ShipdConfig{...} in a self-contained Go file inside your module. The CLI evaluates that file with Go; imported packages and helper declarations in the same file are supported. It does not load sibling Go files, so keep application dependencies in imported packages. Use the same package name as other Go files in its directory; package main above assumes that directory is an application package. Do not define main in the definition file. shipd pull rewrites the Go definitions and regenerates accessors; review the resulting diff because comments and helper code are replaced.

Push

shipd push --env development

Output

Plan:
  + create flag "new-checkout"
  + create flag "search-variant"

Note: definition changes (type, variants, tags, lifecycle, description) apply to all environments.
Note: definition/ownership changes apply to all environments (requires production permission).
Apply this plan? [y/N] y
Applied 2 change(s).
Wrote types for 2 flag(s) to /home/dev/web-app/src/generated/flags.ts

What push did

Created both flags in the project. Definitions (type, variants, description, tags) are shared by every environment.
Enabled them in development, the environment you pushed to, serving their default. Other environments get the flags disabled until you configure them in the dashboard or push to them.
Wrote types to src/generated/flags.ts, for TypeScript; Go projects configured above get internal/flags/flags_gen.go with per-flag accessors. See Generate flag types.

Push never deletes flags that are on the server but missing from the file. The full rules, including --prune, conflicts, and approvals, are in shipd push.

Next steps

Evaluate the flag

Read new-checkout in your app.

Push, pull, and diff

The everyday edit, diff, push loop.

Generate flag types

Use TypeScript types or generated Go accessors.

Sync flags in CI

Diff on pull requests, push on merge.

Reference: defineFlags and config files · CLI

Flags

Config as code

Operations

Enterprise

Migrate to shipd

Define flags in code

Overview

Define the flags

Go definitions

Push

What push did

Next steps

Evaluate the flag

Push, pull, and diff

Generate flag types

Sync flags in CI

​Overview

​Define the flags

​Go definitions

​Push

​What push did

​Next steps

Evaluate the flag

Push, pull, and diff

Generate flag types

Sync flags in CI

Overview

Define the flags

Go definitions

Push

What push did

Next steps