> ## 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.

# Configuration

> Universal strait.json config file shared by all SDKs and the CLI.

Strait uses a universal `strait.json` configuration file that all SDKs and the [CLI](https://github.com/strait-dev/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:

```bash theme={null}
strait init
```

Or create one manually:

```json theme={null}
{
  "$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"
  }
}
```

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

## 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) |

<Warning>
  **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.
</Warning>

## 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

<CodeGroup>
  ```ts TypeScript theme={null}
  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" });
  ```

  ```python Python theme={null}
  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()
  ```

  ```go Go theme={null}
  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"),
  })
  ```
</CodeGroup>

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

* [strait-dev/strait-ruby](https://github.com/strait-dev/strait-ruby)
* [strait-dev/strait-rust](https://github.com/strait-dev/strait-rust)

## Migrating from `strait.config.ts`

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

```bash theme={null}
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:

```bash theme={null}
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`:

```bash theme={null}
strait init --yes --project proj_abc123
```

This uses all defaults without prompting.