Configuration - Strait

Strait uses a universal strait.json configuration file that all SDKs and the CLI can read. This replaces the TypeScript-specific strait.config.ts file (now deprecated).

Getting Started

Run the init command to create a strait.json file:

strait init

Or create one manually:

{
  "$schema": "https://strait.dev/schema.json",
  "project": {
    "id": "proj_abc123",
    "name": "My Project"
  },
  "sdk": {
    "base_url": "https://api.strait.dev",
    "auth_type": "apiKey",
    "timeout_ms": 30000
  },
  "src": "src",
  "runtime": "node",
  "build": {
    "out_dir": ".strait"
  },
  "deploy": {
    "default_environment": "production"
  }
}

The $schema field enables autocomplete and validation in VS Code, IntelliJ, and other editors that support JSON Schema.

Field Reference

`project` (required)

Field	Type	Required	Description
`project.id`	string	yes	Strait project ID. Used by CLI and SDKs.
`project.name`	string	no	Human-readable name. Display only.

`sdk` (optional)

SDK client configuration. These values are read by all five SDKs.

Field	Type	Default	Description
`sdk.base_url`	string	—	API base URL.
`sdk.auth_type`	`"bearer"` \| `"apiKey"` \| `"runToken"`	`"apiKey"`	Authentication strategy.
`sdk.timeout_ms`	integer	`30000`	Request timeout in milliseconds.

CLI fields (optional)

These fields are read by the CLI only. SDKs ignore them.

Field	Type	Default	Description
`src`	string	`"src"`	Source directory scanned for `.job.ts` and `.workflow.ts` definitions.
`runtime`	`"node"` \| `"bun"`	`"node"`	Hosted runtime used by `strait build`.
`build.out_dir`	string	`".strait"`	Compiled build output directory.
`deploy.default_environment`	string	—	Default deployment target environment.

Environment Variable Overrides

Environment variables always take precedence over strait.json values. This lets you use the config file for defaults while overriding per-environment in CI/CD or production.

`strait.json` field	Env var	Wins
`project.id`	`STRAIT_PROJECT`	env var
`sdk.base_url`	`STRAIT_BASE_URL`	env var
`sdk.auth_type`	`STRAIT_AUTH_TYPE`	env var
`sdk.timeout_ms`	`STRAIT_TIMEOUT_MS`	env var
(not in file)	`STRAIT_API_KEY`	env var (only source)

Auth tokens are never stored in strait.json. The API key always comes from the STRAIT_API_KEY environment variable or the CLI profile store (~/.config/strait/). Never commit secrets to version control.

Config File Discovery

All SDKs and the CLI look for strait.json in the current working directory. There is no upward directory traversal — the file must be at the project root where commands are invoked.

SDK discovery order

Explicit path (if provided via options)
strait.json in working directory
strait.config.ts / .js / .mjs / .cjs (deprecated, TypeScript SDK only)

CLI discovery order

Explicit --config flag
strait.json in working directory
strait.config.ts / .js / .mjs / .cjs (deprecated)

CLI connection resolution priority

When the CLI resolves server URL, project ID, and API key, the priority chain is:

CLI flags  >  env vars  >  CLI profile context  >  strait.json

Loading Config from Each SDK

import { createClientFromConfigFile } from "@strait/ts/node";

// Auto-discovers strait.json in cwd
const client = await createClientFromConfigFile();

// Or specify a directory
const client = await createClientFromConfigFile({ cwd: "/path/to/project" });

// Or an explicit path
const client = await createClientFromConfigFile({ configPath: "./config/strait.json" });

from strait import Client, AsyncClient

# Auto-discovers strait.json in cwd
client = Client.from_file()

# Or specify a directory
client = Client.from_file(search_dir="/path/to/project")

# Or an explicit path
client = Client.from_file(path="/path/to/custom-config.json")

# Async variant
async_client = AsyncClient.from_file()

import strait "github.com/strait-dev/strait-go"

// Auto-discovers strait.json in cwd
client, err := strait.NewClientFromFile(nil)

// Or specify a directory
client, err := strait.NewClientFromFile([]strait.ConfigFileOption{
    strait.WithConfigDir("/path/to/project"),
})

// Or an explicit path
client, err := strait.NewClientFromFile([]strait.ConfigFileOption{
    strait.WithConfigPath("/path/to/custom-config.json"),
})

For Ruby and Rust SDK configuration examples, see their dedicated repositories:

Migrating from `strait.config.ts`

If you’re using the deprecated strait.config.ts, run:

strait init

This creates a strait.json file. You can then delete your strait.config.ts. The SDKs and CLI will automatically prefer strait.json when both files exist. When a .ts config file is loaded, the SDK and CLI emit a deprecation warning:

strait.config.ts is deprecated. Run 'strait init' to migrate to strait.json.

`strait init` Command

The strait init command scaffolds a new strait.json interactively:

strait init

It prompts for:

Project ID
Project name (optional)
Source directory (default: src)
Runtime — Node.js or Bun (default: Node.js)
Base URL (optional)

It also checks your .gitignore and offers to add .strait (the build output directory).

Non-interactive mode

For CI/CD or scripting, use --yes with --project:

strait init --yes --project proj_abc123

This uses all defaults without prompting.

​Getting Started

​Field Reference

​project (required)

​sdk (optional)

​CLI fields (optional)

​Environment Variable Overrides

​Config File Discovery

​SDK discovery order

​CLI discovery order

​CLI connection resolution priority

​Loading Config from Each SDK

​Migrating from strait.config.ts

​strait init Command

​Non-interactive mode

Getting Started

Field Reference

`project` (required)

`sdk` (optional)

CLI fields (optional)

Environment Variable Overrides

Config File Discovery

SDK discovery order

CLI discovery order

CLI connection resolution priority

Loading Config from Each SDK

Migrating from `strait.config.ts`

`strait init` Command

Non-interactive mode