Push, pull, and diff

Overview

Three commands keep the local flag config (shipd.config.ts or shipd.config.go) and the server in sync. shipd diff shows what differs, shipd push makes the server match the file, and shipd pull makes the file match the server. There is no lockfile: the server is the source you compare against, and version checks stop you from overwriting someone else’s change.

Command	Direction	Changes	Reference
`shipd diff`	compare	nothing	`shipd diff`
`shipd push`	file → server	flags on the server, then TypeScript types or Go accessors	`shipd push`
`shipd pull`	server → file	the selected TypeScript, Go, or JSON config and generated TypeScript types or Go accessors	`shipd pull`

Each command works on one project and one environment: the ones your credential is bound to, or the ones you pass with --project and --env.

Go definitions

The CLI reads shipd.config.go directly. Push and pull generate Go accessors by default for Go input, unless typesLanguage overrides the output language. Pull writes the current server definitions back to the Go file.

The everyday loop

Edit the file

// shipd.config.ts
    "max-retries": {
      type: "number",
      default: 5, // was 3
      description: "Max retries for outbound API calls",
    },

// Entry inside config.ShipdConfig (import github.com/alasti-company/useshipd.com/sdks/go/config).
"max-retries": {Type: "number", Default: 5, // Was 3.
    Description: "Max retries for outbound API calls"},

Diff

shipd diff --env staging

Output

Plan:
  ~ update flag "max-retries"
      default: 3 -> 5

Every line should be a change you made. A default: line you did not expect usually means someone changed that environment’s fallthrough in the dashboard. Pull before you push, or your push reverts it.

Push

shipd push --env staging

Confirm the plan. Push applies it and regenerates types.

Commit

Commit definitions and generated output together. For Go, include the Go definitions and generated accessors.

default belongs to the environment you push to. Descriptions, tags, types, and variants are shared by every environment. See Field scope.

Pull

Use shipd pull to start from what is live, for example after a teammate edited flags in the dashboard or to resolve a conflict.

shipd pull --env staging

shipd pull rewrites the selected TypeScript, Go, or JSON config from scratch. Comments, formatting, and helper code are lost. Commit or stash the file first, then re-apply anything you need from git diff.

Each flag’s default comes from the fallthrough of the environment you pull from, so pulling from staging and production can give different files.

Flags missing from the file

A flag that is on the server but not in shipd.config.ts is left alone. shipd push warns about it, and shipd diff lists it as - archive flag. To archive those flags, pass --prune on purpose:

shipd diff --env staging        # read every "- archive flag" line
shipd push --prune --env staging

--prune archives every server flag missing from the file, including flags created in the dashboard and demo flags in a new project. Never add --prune to a script you have not diffed.

Flags

Config as code

Operations

Enterprise

Migrate to shipd

Push, pull, and diff

Overview

Go definitions

The everyday loop

Pull

Flags missing from the file

Next steps

​Overview

​Go definitions

​The everyday loop

​Pull

​Flags missing from the file

​Next steps

Overview

Go definitions

The everyday loop

Pull

Flags missing from the file

Next steps