---
title: "Configuration"
description: "Complete reference for arete.toml configuration options."
editUrl: true
head: []
template: "doc"
sidebar: {"order":4,"hidden":false,"attrs":{}}
pagefind: true
draft: false
---

The `arete.toml` file is the central configuration for your Arete project. It defines your project metadata, SDK generation settings, build preferences, and stack definitions. The file is created automatically when you run `a4 init`, but you can customize it for advanced use cases.

---

## Creating the Configuration File

The easiest way to create `arete.toml` is with the CLI:

```bash
a4 init
```

This command:

- Creates `arete.toml` with a project name based on your directory
- Auto-discovers stacks from `.arete/*.stack.json` files
- Creates a `.arete/` directory if it doesn't exist

You can then customize the generated file for your needs.

---

## File Location

By default, the CLI looks for `arete.toml` in the current directory. You can specify a different path with the `--config` flag:

```bash
a4 --config ./config/arete.toml up
```

---

## Minimal Configuration

For most projects, you only need a project name:

```toml
[project]
name = "my-stack"
```

The CLI auto-discovers stacks from `.arete/*.stack.json` files created during `cargo build`.

---

## Full Configuration Reference

```toml
[project]
name = "my-project"
description = "A brief description of your project"
version = "1.0.0"

# SDK generation settings
[sdk]
output_dir = "./generated"                              # Default output for both languages
typescript_output_dir = "./frontend/src/generated"     # Override for TypeScript only
rust_output_dir = "./crates/generated"                 # Override for Rust only
typescript_package = "@myorg/my-sdk"                   # Package name for TypeScript
rust_module_mode = false                               # Generate Rust SDKs as modules by default

# Build preferences
[build]
watch_by_default = true

# Stack definitions (auto-discovered by default, but can be explicit)
[[stacks]]
name = "my-game"
stack = "SettlementGame"                               # Stack name or path to .stack.json
description = "Settlement game tracking"
typescript_output_file = "./src/generated/game.ts"    # Per-stack TypeScript output path
rust_output_crate = "./crates/game-stack"             # Per-stack Rust output path
rust_module = true                                     # Per-stack: generate as module instead of crate
```

---

## Sections

### `[project]` — Project Metadata

| Option        | Type   | Required | Description                                |
| ------------- | ------ | -------- | ------------------------------------------ |
| `name`        | string | Yes      | Project name (used for SDK package naming) |
| `description` | string | No       | Project description                        |
| `version`     | string | No       | Project version                            |

### `[sdk]` — SDK Generation Settings

| Option                  | Type    | Default                       | Description                                                           |
| ----------------------- | ------- | ----------------------------- | --------------------------------------------------------------------- |
| `output_dir`            | string  | `"./generated"`               | Default output directory for all SDKs                                 |
| `typescript_output_dir` | string  | `output_dir`                  | TypeScript SDK output directory                                       |
| `rust_output_dir`       | string  | `output_dir`                  | Rust SDK output directory                                             |
| `typescript_package`    | string  | `"arete-stacks/{stack_name}"` | NPM package name for TypeScript SDKs                                  |
| `rust_module_mode`      | boolean | `false`                       | Generate Rust SDKs as modules (`mod.rs`) instead of standalone crates |

**Note:** When `rust_module_mode = true`, generated Rust SDKs are created as modules that can be embedded directly in your existing crate. When `false`, each SDK is generated as a standalone crate with its own `Cargo.toml`.

### `[build]` — Build Preferences

| Option             | Type    | Default | Description                                                    |
| ------------------ | ------- | ------- | -------------------------------------------------------------- |
| `watch_by_default` | boolean | `true`  | Enable file watching for automatic rebuilds during development |

### `[[stacks]]` — Stack Definitions

Define stacks explicitly for custom naming or per-stack overrides. If not defined, stacks are auto-discovered from `.arete/*.stack.json` files.

| Option                   | Type    | Required | Description                                                  |
| ------------------------ | ------- | -------- | ------------------------------------------------------------ |
| `name`                   | string  | Yes      | Stack name (used for SDK generation and CLI commands)        |
| `stack`                  | string  | Yes      | Stack name from your Rust code or path to `.stack.json` file |
| `description`            | string  | No       | Stack description                                            |
| `typescript_output_file` | string  | No       | Per-stack TypeScript output file path                        |
| `rust_output_crate`      | string  | No       | Per-stack Rust output crate/module directory                 |
| `rust_module`            | boolean | No       | Per-stack override for module vs crate generation            |

---

## Common Use Cases

### Multiple Stacks in One Project

Each stack is a separate `#[arete]` module that can contain multiple entities. Use multiple `[[stacks]]` entries when you have separate programs or data sources:

```toml
[project]
name = "my-defi-protocol"

[[stacks]]
name = "lending"
stack = "LendingMarket"
description = "Lending pool positions and interest rates"

[[stacks]]
name = "dex"
stack = "DexPool"
description = "DEX liquidity pools and swaps"
```

### Separate SDK Output Directories

```toml
[project]
name = "my-project"

[sdk]
typescript_output_dir = "./frontend/src/generated"
rust_output_dir = "./crates/generated"
```

### Custom TypeScript Package Name

```toml
[project]
name = "my-project"

[sdk]
typescript_package = "@myorg/arete-sdk"
```

### Rust SDK as Module (for Monorepos)

```toml
[project]
name = "my-project"

[sdk]
rust_module_mode = true  # All Rust SDKs generated as modules
```

Or per-stack:

```toml
[[stacks]]
name = "my-game"
stack = "SettlementGame"
rust_module = true
rust_output_crate = "./src/generated"  # Will create mod.rs here
```

### Per-Stack TypeScript Output File

```toml
[[stacks]]
name = "game"
stack = "GameState"
typescript_output_file = "./src/game.ts"
```

---

## Environment Variables

Environment variables override configuration file values:

| Variable        | Description                | Overrides          |
| --------------- | -------------------------- | ------------------ |
| `ARETE_API_URL` | Override the API endpoint  | Default API URL    |
| `ARETE_API_KEY` | API key for authentication | (no file override) |

---

## Credentials File

Authentication credentials are stored separately from your project configuration in:

```
~/.arete/credentials.toml
```

This file contains your API key for accessing Arete Cloud:

```toml
api_key = "your-api-key-here"
```

The credentials file is created automatically when you authenticate via the CLI. Since this file contains sensitive information, it is stored in your home directory and should never be committed to version control.

:::tip[Closed Beta]
During closed beta, you need an API key to deploy. [Contact us on X](https://x.com/usearete) to request access.
:::

---

## Validation

Validate your configuration:

```bash
a4 config validate
```

This checks:

- Required fields are present
- File paths are valid
- Stack references resolve to valid `.stack.json` files
- No conflicting settings

---

## Next Steps

- [CLI Commands](/cli/commands) — Full CLI reference
- [Your First Stack](/building-stacks/your-first-stack) — Complete tutorial
- [SDK Reference: Rust](/sdks/rust) — Rust SDK usage and module mode