#Configuration

#HTTP host and port

Set via environment variables, read at startup:

PORT=8080 HTTP_HOST=127.0.0.1 shipplane-lite

#Config file

On startup, Shipplane Lite looks for a config file in:

$XDG_CONFIG_HOME/shipplane/lite.config.{ts,mjs,js,cjs}

If XDG_CONFIG_HOME is unset, it falls back to ~/.config/shipplane/. The first matching file (checked in the order .ts, .mjs, .js, .cjs) is loaded and merged over the defaults; the rest are ignored.

The file's default export is an object shaped like:

interface AppConfig {
  http: {
    addr: string;
    port: number;
  };
  workflows?: WorkflowDefinition[];
  registry?: TaskRegistry;
}

registry merges one TaskRegistry (built with @shipplane/core's createTaskRegistry()) on top of the built-in 3 task types — see Custom task types.

#TypeScript example

workflows entries are plain WorkflowDefinition JSON, so building them with @shipplane/core's workflow() builder gives you type checking and autocomplete. Install core in the config directory:

cd ~/.config/shipplane
npm install @shipplane/core

~/.config/shipplane/lite.config.ts:

import { workflow } from "@shipplane/core";

const deploy = workflow("deploy").task("install", {
  type: "@shipplane/local_cmd",
  params: { cmd: "echo hi" },
});

export default {
  http: { addr: "0.0.0.0", port: 4000 },
  workflows: [deploy.toJSON()],
};

The config loader runs your .ts file directly through Node's built-in TypeScript support — there's no bundler resolving imports. If you split your config across files, relative imports need an explicit extension (import { deploy } from "./workflows/deploy.ts", not "./workflows/deploy") or Node will fail to resolve them.

#Workflow seeding

Workflows listed under workflows in the config file are upserted into the local database on every startup (matched and updated by workflow id). This is how you check a workflow definition into a config file and have it available without using the editor UI.

Seeding runs unless disabled — see --no-sync below.

Shipplane Lite caps workflows at 10 total, and seeding isn't exempt: a seed entry with a new id counts as a new workflow and is blocked past the cap same as one created through the UI or HTTP API. Only re-seeding an id that already exists updates it in place and doesn't count against the cap.

#CLI flags

shipplane-lite [--version] [--no-sync]