Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.strait.dev/llms.txt

Use this file to discover all available pages before exploring further.

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)

FieldTypeRequiredDescription
project.idstringyesStrait project ID. Used by CLI and SDKs.
project.namestringnoHuman-readable name. Display only.

​
sdk (optional)

SDK client configuration. These values are read by all five SDKs.
FieldTypeDefaultDescription
sdk.base_urlstring—API base URL.
sdk.auth_type"bearer" | "apiKey" | "runToken""apiKey"Authentication strategy.
sdk.timeout_msinteger30000Request timeout in milliseconds.

​
CLI fields (optional)

These fields are read by the CLI only. SDKs ignore them.
FieldTypeDefaultDescription
srcstring"src"Source directory scanned for *.job.ts and *.workflow.ts definitions.
runtime"node" | "bun""node"Hosted runtime used by strait build.
build.out_dirstring".strait"Compiled build output directory.
deploy.default_environmentstring—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 fieldEnv varWins
project.idSTRAIT_PROJECTenv var
sdk.base_urlSTRAIT_BASE_URLenv var
sdk.auth_typeSTRAIT_AUTH_TYPEenv var
sdk.timeout_msSTRAIT_TIMEOUT_MSenv var
(not in file)STRAIT_API_KEYenv 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

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

​
CLI discovery order

  1. Explicit --config flag
  2. strait.json in working directory
  3. 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" });
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:
  1. Project ID
  2. Project name (optional)
  3. Source directory (default: src)
  4. Runtime — Node.js or Bun (default: Node.js)
  5. 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.