### Setup Project Keys and Dependencies (Shell)

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

This script orchestrates the initial setup of the project, focusing on generating necessary keys and installing dashboard dependencies. It first ensures keys are set up by running a script within the 'scripts' directory and then proceeds to install the dashboard's node modules.

```shell
bun run scr:setup:keys && bun run dash:install
```

--------------------------------

### Automated Team Setup using Axogen CLI

Source: https://github.com/axonotes/axogen/blob/main/website/docs/Why Use Axogen In/01-nextjs-react.md

This Bash command demonstrates how to initiate the automated setup process for new team members using the Axogen CLI. The 'team-setup' command, defined in the configuration, handles tasks like installing dependencies, generating and pushing database migrations, and providing instructions for further configuration.

```bash
git clone your-app
cd your-app
axogen run team-setup     # Automated setup with validation

```

--------------------------------

### Setup Microservices Environment Command

Source: https://github.com/axonotes/axogen/blob/main/website/docs/Why Use Axogen In/00-microservices.md

A command to set up the entire microservices development environment. It starts necessary infrastructure like Docker containers for PostgreSQL and Redis, waits for the database to be ready, and creates databases for each service. Finally, it indicates the environment is ready for development.

```typescript
setup: cmd({
            help: "Set up the entire microservices development environment",
            exec: async () => {
                console.log("🚀 Setting up microservices environment...");

                // Start infrastructure
                await liveExec("docker-compose up -d postgres redis");

                // Wait for database to be ready
                console.log("⏳ Waiting for database to be ready...");
                await liveExec("sleep 5");

                // Create databases for each service
                for (const service of services) {
                    console.log(`📦 Creating database: ${service.database}`);
                    await liveExec(
                        `docker exec postgres createdb -U ${envVars.DB_USER} ${service.database} || true`
                    );
                }

                console.log(
                    "✅ Environment ready! Run 'axogen run dev' to start all services"
                );
            },
        })
```

--------------------------------

### Axogen CLI Commands

Source: https://github.com/axonotes/axogen/blob/main/website/docs/02-getting-started.md

Provides a reference for common Axogen command-line interface (CLI) commands. These include generating configurations, running custom commands, and accessing help information.

```bash
# Generate all targets
axogen generate

# Generate specific target
axogen generate --target app

# See what would be generated (without writing files)
axogen generate --dry-run

# Run commands
axogen run start

# Get help on any command
axogen run --help
axogen generate --help
```

--------------------------------

### Example .env.axogen File Content

Source: https://github.com/axonotes/axogen/blob/main/website/docs/Why Use Axogen In/00-microservices.md

An example of a fully configured .env.axogen file. It provides concrete values for database credentials, service URLs, and external service keys. This file should be created and populated by developers to override the defaults in .env.example.

```bash
# .env.axogen
NODE_ENV=development

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=mypassword123

# Service URLs (environment-aware)
AUTH_SERVICE_URL=http://localhost:3001
ORDER_SERVICE_URL=http://localhost:3002
PAYMENT_SERVICE_URL=http://localhost:3003

# External services
REDIS_URL=redis://localhost:6379
STRIPE_SECRET_KEY=sk_test_abcd1234
JWT_SECRET=my-super-secret-jwt-key-32-chars
```

--------------------------------

### Verify Axogen Installation

Source: https://github.com/axonotes/axogen/blob/main/website/docs/01-installation.md

Checks if Axogen has been installed correctly by displaying its current version. This command is useful after installation to confirm the setup was successful. Requires Axogen to be in your system's PATH.

```bash
axogen --version
```

--------------------------------

### Initialize Local Environment Variables

Source: https://github.com/axonotes/axogen/blob/main/website/docs/Why Use Axogen In/01-nextjs-react.md

Copies the example environment file to a local version and instructs on filling in necessary values. This is a crucial first step before running the development server.

```bash
cp .env.example .env.local
# Fill in values in .env.local
```

--------------------------------

### Axogen Installation (npm/yarn)

Source: https://github.com/axonotes/axogen/blob/main/website/docs/00-intro.md

Standard command to install the Axogen package using npm or yarn.

```bash
npm install @axonotes/axogen
```

--------------------------------

### Axogen Command Definitions

Source: https://github.com/axonotes/axogen/blob/main/website/docs/08-advanced.md

Defines custom commands 'setup' and 'deploy' for the Axogen CLI. 'setup' initializes the development environment using docker-compose and Prisma. 'deploy' handles building the application and deploying it based on the environment.

```typescript
import { cmd, liveExec } from "@axonotes/axogen";
import { z } from "zod";

// Assume packageInfo and envVars are defined elsewhere as in the previous example
const packageInfo = {
    name: "example-app",
    version: "1.0.0"
};
const envVars = {
    NODE_ENV: process.env.NODE_ENV || "development"
};

const commands = {
    setup: cmd({
        help: "Set up the development environment",
        exec: async (ctx) => {
            console.log("Setting up development environment...");
            await liveExec("docker-compose up -d");
            await liveExec("npx prisma db push");
            await liveExec("npx prisma db seed");
            console.log("Development environment ready!");
        },
    }),

    deploy: cmd({
        help: "Deploy to the current environment",
        options: {
            build: z.boolean().default(true).describe("Build before deploying"),
        },
        exec: async (ctx) => {
            console.log(
                `Deploying ${packageInfo.name} v${packageInfo.version}...`
            );

            if (ctx.options.build) {
                await liveExec("npm run build");
            }

            if (envVars.NODE_ENV === "production") {
                await liveExec("kubectl apply -f k8s/");
            } else {
                await liveExec("docker-compose up -d");
            }
        },
    }),
};

// Export commands for use in Axogen config
// export default commands;

```

--------------------------------

### Define Intelligent Project Setup and Deployment Commands

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

Defines intelligent commands for project setup and deployment using `command.define` with options validation via Zod. This allows for typed options, runtime validation, and environment-specific logic.

```typescript
commands: {
    setup: command.define({
        help: "Initialize the project with key generation",
        exec: async (ctx) => {
            if (!env.JWT_PRIVATE_KEY_BASE64) {
                console.log("🔑 Generating JWT keys...");
                // Generate and save keys automatically
                console.log("✅ Keys generated! Update your .env.axogen");
            } else {
                console.log("✅ Keys already exist");
            }
        },
    }),

    deploy: command.define({
        help: "Deploy the application",
        options: {
            environment: z.enum(["staging", "production"]).default("staging"),
            skipTests: z.boolean().default(false),
        },
        exec: async (ctx) => {
            if (ctx.options.environment === "production" && !ctx.options.skipTests) {
                console.log("🧪 Running tests before production deploy...");
                // Run tests with live output
            }

            console.log(`🚀 Deploying to ${ctx.options.environment}...`);
            // Smart deployment logic based on environment
        },
    }),
}
```

--------------------------------

### Install Axogen using npm or yarn

Source: https://github.com/axonotes/axogen/blob/main/website/docs/01-installation.md

Installs the latest version of Axogen using npm or yarn. Ensure you have Node.js 18+ or Bun 1.2+ installed. This command fetches and installs the package and its dependencies.

```bash
npm install @axonotes/axogen@latest
```

```bash
yarn add @axonotes/axogen@latest
```

--------------------------------

### Start SpacetimeDB Development Server (Shell)

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

This command starts the SpacetimeDB development server. It utilizes the locally built SpacetimeDB CLI, runs it in-memory, and configures allowed OpenID Connect (OIDC) issuer URLs for authentication. The hardcoded 'http://localhost:5173' is a critical configuration point for the dashboard's callback URL.

```shell
./bin/spacetimedb-cli start --in-memory --allowed-oidc-issuer http://localhost:5173 --allowed-oidc-issuer https://auth.spacetimedb.com
```

--------------------------------

### Start Development Server Command

Source: https://github.com/axonotes/axogen/blob/main/website/docs/Why Use Axogen In/00-microservices.md

Command to start all microservices in development mode. It utilizes docker-compose to build and then run all services concurrently. This is the primary command for local development.

```typescript
dev: cmd({
            help: "Start all services in development mode",
            exec: async () => {
                console.log("🚀 Starting all microservices...");
                await liveExec("docker-compose up --build");
            },
        })
```

--------------------------------

### Example .env.axogen Configuration

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

This is an example of a .env.axogen file which holds the actual values for the environment variables defined in the TypeScript configuration file. It provides the necessary values for ports, database URL, and other configuration parameters that are used by Axogen.

```bash
```bash
PACETIME_PORT=3000
DASHBOARD_PORT=5173
WORKOS_CLIENT_ID=your_client_id
DATABASE_URL=postgresql://localhost:5432/axonotes
JWT_PRIVATE_KEY_BASE64=eW91cl9wcml2YXRlX2tleQ==
NODE_ENV=development
```
```

--------------------------------

### Start Local Development Server with Yarn

Source: https://github.com/axonotes/axogen/blob/main/website/README.md

Starts a local development server for the website. This command enables live reloading, allowing changes to be reflected in the browser without a manual server restart.

```bash
yarn start
```

--------------------------------

### Manage Dashboard Dependencies and Run Commands (Shell)

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

These scripts manage the SvelteKit dashboard's development lifecycle. They include installing Node.js dependencies, starting the development server, building the project for production, and previewing the production build. Each command operates within the 'dashboard' directory.

```shell
cd dashboard && bun install
```

```shell
cd dashboard && bun run dev
```

```shell
cd dashboard && bun run build
```

```shell
cd dashboard && bun run preview
```

--------------------------------

### Create Basic Axogen Config (TypeScript)

Source: https://github.com/axonotes/axogen/blob/main/website/docs/02-getting-started.md

Defines the absolute minimum configuration for Axogen to generate an .env file. It initializes a target named 'app' with hardcoded environment variables.

```typescript
import {defineConfig, env} from "@axonotes/axogen";

export default defineConfig({
    targets: {
        app: env({
            path: "app/.env",
            variables: {
                NODE_ENV: "development",
                PORT: 3000,
            },
        }),
    },
});
```

--------------------------------

### Run Development Server

Source: https://github.com/axonotes/axogen/blob/main/website/docs/Why Use Axogen In/01-nextjs-react.md

Command to start the development server for the AxoNotes Axogen project. Assumes environment variables are correctly set in .env.local.

```bash
npm run dev
```

--------------------------------

### Create and Generate with Axogen Configuration

Source: https://github.com/axonotes/axogen/blob/main/website/docs/01-installation.md

Demonstrates creating a minimal Axogen configuration file and then generating output using it. This requires Node.js and TypeScript. It creates a temporary config, runs the generation, and cleans up. The config defines environment variables and target paths.

```typescript
echo 'import { defineConfig, env } from "@axonotes/axogen";

export default defineConfig({
    targets: {
        test: env({
            path: "test.env",
            variables: {
                NODE_ENV: "development",
                PORT: 3000,
            },
        }),
    },
});' > axogen.config.ts

# Generate it
axogen generate

# Clean up the mess
rm axogen.config.ts test.env
```

--------------------------------

### Install and Configure Axogen

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

This snippet demonstrates how to install the Axogen CLI using npm, create a minimal configuration file (axogen.config.ts) using echo and TypeScript, and set up a corresponding environment file (.env.axogen). Finally, it shows how to generate the configuration.

```bash
# Install axogen (npm, bun, yarn, etc.)
npm install @axonotes/axogen

# Create a minimal config using echo
echo 'import {defineConfig, loadEnv, z} from "@axonotes/axogen";
const env = loadEnv(z.object({
    NODE_ENV: z.string().default("development"),
    PORT: z.coerce.number().default(3000),
    DATABASE_URL: z.url(),
}));
export default defineConfig({
    targets: {
        app: {
            path: ".env",
            type: "env",
            variables: {
                NODE_ENV: env.NODE_ENV,
                PORT: env.PORT,
                DATABASE_URL: env.DATABASE_URL,
            },
        },
    },
});' > axogen.config.ts

# Create a matching .env.axogen file using echo
echo 'NODE_ENV=development
PORT=3000
DATABASE_URL=https://your.database.url' > .env.axogen

# Generate your config with validation
axogen generate
```

--------------------------------

### Axogen Generate Command Example

Source: https://github.com/axonotes/axogen/blob/main/website/docs/Why Use Axogen In/00-microservices.md

This snippet shows the output of the 'axogen generate' command, illustrating the .env files and docker-compose.yml generated for different services in a microservice project.

```bash
project/
├── auth-service/.env          # ✅ Perfectly configured for auth service
├── orders-service/.env        # ✅ Has auth service URL automatically
├── payments-service/.env      # ✅ Has order service URL automatically
├── notifications-service/.env # ✅ Has auth service URL automatically
├── docker-compose.yml         # ✅ All services coordinated
├── k8s/configmap.yaml         # ✅ Production configuration (if NODE_ENV=production)
└── .env.example               # ✅ Perfect onboarding for new developers
```

--------------------------------

### Install Project Dependencies with Yarn

Source: https://github.com/axonotes/axogen/blob/main/website/README.md

Installs all necessary project dependencies using the Yarn package manager. This is a prerequisite for running other development or build commands.

```bash
yarn
```

--------------------------------

### Axogen CLI Commands for Configuration Management (Bash)

Source: https://context7.com/axonotes/axogen/llms.txt

Demonstrates how to install and use the Axogen CLI to manage configuration files. This includes creating configuration files, generating configurations, and running defined commands.

```bash
# Install Axogen
npm install @axonotes/axogen

# Create configuration file (axogen.config.ts)
cat > axogen.config.ts << 'EOF'
import { defineConfig, env } from "@axonotes/axogen";

export default defineConfig({
  targets: {
    app: env({
      path: ".env",
      variables: {
        NODE_ENV: "development",
        PORT: 3000,
      },
    }),
  },
  commands: {
    dev: "npm run dev",
    build: "npm run build",
  },
});
EOF

# Create environment source file (.env.axogen)
cat > .env.axogen << 'EOF'
NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://localhost:5432/myapp
EOF

# Generate all configuration files
axogen generate

# Generate specific target
axogen generate api

# Generate with verbose output
axogen generate --verbose

# Run a defined command
axogen run dev

# Run nested command
axogen run database migrate

# Run command with options
axogen run deploy --environment production --skip-tests

# Show help
axogen --help
axogen generate --help
axogen run --help

# Show version
axogen --version

# List available commands
axogen run --help

```

--------------------------------

### Install and Generate Config with Axogen (Bash)

Source: https://github.com/axonotes/axogen/blob/main/README.md

This snippet demonstrates how to install Axogen using npm and create a basic configuration file (`axogen.config.ts`). It then shows how to generate configurations and run commands using the Axogen CLI.

```bash
# Install
npm install @axonotes/axogen

# Create basic config
echo 'import {defineConfig, env} from "@axonotes/axogen";

export default defineConfig({
    targets: {
        app: env({
            path: ".env",
            variables: {
                NODE_ENV: "development",
                PORT: 3000,
            },
        }),
    },
});' > axogen.config.ts

# Generate
axogen generate

# Run commands
axogen run --help
```

--------------------------------

### Generate Utility Keys (Shell)

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

This script is responsible for generating utility keys, likely for cryptographic purposes or authentication. It first ensures any necessary dependencies within the 'scripts' directory are installed using 'bun install' and then executes the 'generate-keys.ts' script.

```shell
cd scripts && bun install
```

```shell
cd scripts && bun run generate-keys.ts
```

--------------------------------

### Execute Advanced Commands (Bash)

Source: https://github.com/axonotes/axogen/blob/main/website/docs/05-commands.md

These bash commands illustrate how to invoke the defined Axonotes Axogen commands with their respective arguments and options. They show examples for the 'migrate' command, specifying direction and steps, and for the 'deploy' command, specifying the environment and force option. These examples demonstrate the practical usage of the commands defined in TypeScript.

```bash
axogen run migrate up --steps 3
axogen run migrate down --dry
axogen run deploy production --force
```

--------------------------------

### Axogen - `.gitignore` Example

Source: https://github.com/axonotes/axogen/blob/main/website/docs/07-secrets.md

This is a sample `.gitignore` file demonstrating common entries for excluding environment files, generated configurations, and directories containing secrets. Proper `.gitignore` usage is crucial for Axogen's Git integration.

```gitignore
# Environment files
.env.local
.env.production
secrets/

# Generated configs with secrets
config/production.json
k8s/secrets.yaml
```

--------------------------------

### Generate Custom Formats with Axogen Template Type (TypeScript)

Source: https://github.com/axonotes/axogen/blob/main/website/docs/99-faq.md

This example demonstrates how to use the 'template' type in Axogen to generate custom file formats not directly supported. It shows the import of necessary functions, defining the configuration with a 'custom' target, specifying the output path, template file, templating engine, and variables to pass.

```typescript
import {defineConfig, template} from "@axonotes/axogen";

export default defineConfig({
    targets: {
        custom: template({
            path: "my-config.xml",
            template: "my-template.xml.njk",
            engine: "nunjucks", // (default: "nunjucks")
            variables: env,
        }),
    },
});
```

--------------------------------

### New Team Member Onboarding with Axogen

Source: https://github.com/axonotes/axogen/blob/main/website/docs/Why Use Axogen In/00-microservices.md

Demonstrates the streamlined onboarding process for new team members using Axogen commands, including cloning the repository, generating configurations, and setting up the development environment.

```bash
git clone the-project
cp .env.example .env.axogen  # Fill in your actual values
axogen generate              # Generate all service configs
axogen run setup             # Set up databases and infrastructure
axogen run dev               # Start everything
```

--------------------------------

### Install Axogen Latest Version (Bash)

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-30-holy-shit-this-escalated-quickly.mdx

Command to install the latest version of the `@axonotes/axogen` package using npm. This is the recommended way to get the newest features and improvements.

```bash
npm install @axonotes/axogen@latest

```

--------------------------------

### Generate .env.example File

Source: https://github.com/axonotes/axogen/blob/main/website/docs/Why Use Axogen In/00-microservices.md

Creates a sample .env file for developers to configure their local environment. It defines essential variables for database connections, service URLs, and external service credentials. Developers should copy this to .env.axogen and fill in their specific values.

```typescript
env({
            path: ".env.example",
            variables: {
                NODE_ENV: "development",

                // Database
                DB_HOST: "localhost",
                DB_PORT: "5432",
                DB_USER: "postgres",
                DB_PASSWORD: "placeholder-put-your-db-password-here",

                // Development service URLs
                AUTH_SERVICE_URL: "http://localhost:3001",
                ORDER_SERVICE_URL: "http://localhost:3002",
                PAYMENT_SERVICE_URL: "http://localhost:3003",

                // External services
                REDIS_URL: "redis://localhost:6379",
                STRIPE_SECRET_KEY: "sk_test_your_test_key_here",
                JWT_SECRET: "placeholder-put-your-32-character-jwt-secret-here",
            },
        })
```

--------------------------------

### Staging Deployment with Axogen

Source: https://github.com/axonotes/axogen/blob/main/website/docs/Why Use Axogen In/00-microservices.md

Illustrates the efficient deployment to a staging environment using Axogen. It highlights how Axogen ensures consistent configuration updates across all services by setting the NODE_ENV and running the generate command.

```bash
NODE_ENV=staging axogen generate  # All configs updated consistently
axogen run deploy --environment staging
```

--------------------------------

### Generate Multiple Output Formats (TypeScript)

Source: https://github.com/axonotes/axogen/blob/main/website/docs/02-getting-started.md

Demonstrates how to configure Axogen to generate the same data in multiple formats, such as .env and JSON. This allows for a single source of truth for configuration shared across different application layers.

```typescript
import {defineConfig, env, json, loadEnv} from "@axonotes/axogen";
import * as z from "zod";

const envVars = loadEnv(
    z.object({
        PORT: z.coerce.number().default(3000),
        DATABASE_URL: z.string(),
    })
);

export default defineConfig({
    targets: {
        app: env({
            path: "app/.env",
            variables: {
                PORT: envVars.PORT,
                DATABASE_URL: envVars.DATABASE_URL,
            },
        }),
        config: json({
            path: "config.json",
            variables: {
                database: {
                    url: envVars.DATABASE_URL,
                },
                server: {
                    port: envVars.PORT,
                },
            },
        }),
    },
});
```

--------------------------------

### Axogen CLI Commands - Bash

Source: https://github.com/axonotes/axogen/blob/main/website/docs/00-intro.md

Demonstrates basic Axogen CLI commands for generating configuration files and running development tasks. These commands are essential for setting up and managing the project's development environment.

```bash
axogen generate    # Generate all config files
axogen run dev     # Run commands with validation
```

--------------------------------

### Add Custom Commands to Axogen Config (TypeScript)

Source: https://github.com/axonotes/axogen/blob/main/website/docs/02-getting-started.md

Shows how to define custom commands within the Axogen configuration file. These commands can be executed using the `axogen run` command, enabling task automation alongside configuration generation.

```typescript
export default defineConfig({
    targets: {
        // ... your targets
    },
    commands: {
        start: "npm start",
        dev: "npm run dev",
    },
});
```

--------------------------------

### Add Environment Variables with Zod Validation (TypeScript)

Source: https://github.com/axonotes/axogen/blob/main/website/docs/02-getting-started.md

Enhances the Axogen configuration to load environment variables from a .env.axogen file using Zod for validation. It ensures that required variables like PORT and DATABASE_URL are present and correctly typed.

```typescript
import {defineConfig, env, loadEnv} from "@axonotes/axogen";
import * as z from "zod";

const envVars = loadEnv(
    z.object({
        PORT: z.coerce.number().default(3000),
        DATABASE_URL: z.string(),
    })
);

export default defineConfig({
    targets: {
        app: env({
            path: "app/.env",
            variables: {
                PORT: envVars.PORT,
                DATABASE_URL: envVars.DATABASE_URL,
            },
        }),
    },
});
```

--------------------------------

### Run Axogen with Different Themes

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

Demonstrates how to run Axogen development server with various predefined themes. Each theme offers a distinct visual style for terminal output, analogous to VS Code themes.

```shell
axogen run dev:all --theme aura          # Vibrant neon colors
axogen run dev:all --theme catppuccin    # Soothing pastels
axogen run dev:all --theme doom-one      # Classic sophisticated
axogen run dev:all --theme astrodark     # Default balanced theme
```

--------------------------------

### Example .env file for a SvelteKit frontend

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

This .env file demonstrates how configuration variables like redirect URIs and WebSocket endpoints are typically stored for a frontend application. It highlights the potential for errors due to hardcoded values and the need for consistency across different services.

```bash
WORKOS_REDIRECT_URI="http://localhost:5173/auth/callback"
PUBLIC_SPACETIME_WS="ws://localhost:3000"
```

--------------------------------

### Define Simple Development Commands

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

Defines basic development commands as strings, referencing environment variables for configuration. This is the simplest way to integrate with Axogen's command runner.

```typescript
export default defineConfig({
    // ... targets
    commands: {
        "dev:spacetime": `./bin/spacetimedb-cli start --in-memory --allowed-oidc-issuer http://localhost:${env.DASHBOARD_PORT}`,
        "dev:dashboard": `cd dashboard && bun run dev --port ${env.DASHBOARD_PORT}`,
    },
});
```

--------------------------------

### Manage SpacetimeDB CLI Login/Logout (Shell)

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

These commands facilitate logging into and out of the SpacetimeDB CLI. They first ensure the CLI is built by running 'sdb:build:cli' and then execute the respective login or logout commands.

```shell
./bin/spacetimedb-cli login
```

```shell
./bin/spacetimedb-cli logout
```

--------------------------------

### Define Advanced Development Commands with Logic

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

Defines development commands using `command.define`, enabling help messages, custom execution logic, and integration with external processes via `liveExec`. This provides more control and user feedback.

```typescript
export default defineConfig({
    commands: {
        "dev:spacetime": command.define({
            help: "Start SpacetimeDB server in development mode",
            exec: async () => {
                console.log("🚀 Starting SpacetimeDB server...");
                const result = await liveExec(
                    `./bin/spacetimedb-cli start --in-memory --allowed-oidc-issuer http://localhost:${env.DASHBOARD_PORT}`,
                    {outputPrefix: "SDB"}
                );
            },
        }),

        "dev:all": command.string(
            "concurrently 'axogen run dev:spacetime' 'axogen run dev:dashboard'",
            "Start all development servers"
        ),
    },
});
```

--------------------------------

### Build and Manage SpacetimeDB CLI (Shell)

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

This script builds the SpacetimeDB CLI and standalone binaries for the project. It creates a 'bin' directory if it doesn't exist, compiles Rust code in the SpacetimeDB directory, and copies the resulting executables to the 'bin' folder. This is a prerequisite for many other SpacetimeDB-related commands.

```shell
mkdir -p bin && cd SpacetimeDB && cargo build --release -p spacetimedb-cli -p spacetimedb-standalone && cp target/release/spacetimedb-cli ../bin/ && cp target/release/spacetimedb-standalone ../bin/
```

--------------------------------

### Type-Safe Configuration with Zod Schema

Source: https://github.com/axonotes/axogen/blob/main/website/docs/03-basic-configuration.md

Axogen uses Zod for runtime validation and TypeScript for compile-time type safety. This example demonstrates defining a JSON target with a Zod schema for validation.

```typescript
import {defineConfig, json} from "@axonotes/axogen";
import * as z from "zod";

export default defineConfig({
    targets: {
        config: json({
            path: "output/config.json",
            schema: z.object({
                name: z.string().describe("The service name"),
                version: z.string().describe("The service version"),
                port: z.number().min(1).max(65535).describe("Server port"),
            }),
            variables: {
                name: "MyService",
                version: "1.2.3",
                port: 3000,
            },
        }),
    },
});
```

--------------------------------

### View SpacetimeDB Server Logs (Shell)

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

This command fetches and displays the logs generated by the SpacetimeDB server for the specified project ('axonotes'). It's essential for debugging server-side issues.

```shell
./bin/spacetimedb-cli logs axonotes
```

--------------------------------

### Implement Conditional Generation in TypeScript

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-30-holy-shit-this-escalated-quickly.mdx

Allows for conditional generation of configuration files based on a boolean 'condition'. This example generates production secrets only when NODE_ENV is set to 'production'.

```typescript
export default defineConfig({
    targets: {
        productionSecrets: env({
            path: "secrets/.env.prod",
            variables: {
                REAL_API_KEY: "super-secret-key",
                PROD_DATABASE_URL: "postgres://prod-server/db",
            },
            condition: process.env.NODE_ENV === "production",
        }),
    },
});
```

--------------------------------

### Define and Generate Configuration with Axogen (TypeScript)

Source: https://github.com/axonotes/axogen/blob/main/website/docs/00-intro.md

This snippet demonstrates how to define a project's configuration using Axogen. It uses `defineConfig`, `loadEnv`, and `env` to specify environment variables with Zod validation and define output targets for `.env` and JSON files. It also shows how to define a custom command with associated logic.

```typescript
import {defineConfig, loadEnv, env, json, cmd} from "@axonotes/axogen";
import * as z from "zod";

const envVars = loadEnv(
    z.object({
        DATABASE_URL: z.url(),
        PORT: z.coerce.number().default(3000),
        NODE_ENV:
            z.enum(["development", "staging", "production"])
            .default("development"),
    })
);

export default defineConfig({
    targets: {
        app: env({
            path: "app/.env",
            variables: {
                DATABASE_URL: envVars.DATABASE_URL,
                PORT: envVars.PORT,
            },
        }),
        config: json({
            path: "config.json",
            variables: {
                database: {url: envVars.DATABASE_URL},
                server: {port: envVars.PORT},
            },
        }),
    },
    commands: {
        start: `npm start --port ${envVars.PORT}`,
        dev: cmd({
            help: "Start development server",
            exec: async () => {
                console.log(`🚀 Starting server on port ${envVars.PORT}`);
                // Your custom logic here
            },
        }),
    },
});
```

--------------------------------

### Configure Local Development Environment with Axogen

Source: https://github.com/axonotes/axogen/blob/main/website/docs/08-advanced.md

This TypeScript code configures the local development environment using Axogen. It defines targets for local environment variables (`.env.local`) and Docker Compose setup (`docker-compose.yml`), including database and Redis services.

```typescript
import {env, yaml, json} from "@axonotes/axogen";

const devConfig = defineConfig({
    targets: {
        // Local development environment
        localEnv: env({
            path: ".env.local",
            variables: {
                ...baseVariables,
                DATABASE_URL:
                    "postgres://postgres:password@localhost:5432/myapp_dev",
                NEXTAUTH_URL: "http://localhost:3000",
                NEXTAUTH_SECRET: "dev-secret-not-for-production",
                REDIS_URL: "redis://localhost:6379",
            },
        }),

        // Docker Compose for local services
        dockerCompose: yaml({
            path: "docker-compose.yml",
            variables: {
                version: "3.8",
                services: {
                    postgres: {
                        image: "postgres:15-alpine",
                        environment: {
                            POSTGRES_DB: `${packageInfo.name}_dev`,
                            POSTGRES_USER: "postgres",
                            POSTGRES_PASSWORD: "placeholder-password",
                        },
                        ports: ["5432:5432"],
                        volumes: ["postgres_data:/var/lib/postgresql/data"],
                    },
                    redis: {
                        image: "redis:7-alpine",
                        ports: ["6379:6379"],
                    },
                },
                volumes: {
                    postgres_data: {},
                },
            },
        }),
    },
});

```

--------------------------------

### Axogen - Docker Secrets Configuration

Source: https://github.com/axonotes/axogen/blob/main/website/docs/07-secrets.md

This example demonstrates how to configure Axogen for Docker environments using the `env` target. It shows how to use the `unsafe` function for development credentials, emphasizing that the Docker environment file (`docker/.env`) should be gitignored.

```typescript
import {defineConfig, env, unsafe} from "@axonotes/axogen";

export default defineConfig({
    targets: {
        // Docker Compose with development credentials
        dockerEnv: env({
            path: "docker/.env", // Make sure this is gitignored!
            variables: {
                POSTGRES_PASSWORD: unsafe(
                    "dev-password-123",
                    "Docker development database password"
                ),
                REDIS_PASSWORD: unsafe(
                    "redis-dev-pass",
                    "Docker development Redis password"
                ),
            },
        }),
    },
});
```

--------------------------------

### Format Server Rust Code (Shell)

Source: https://github.com/axonotes/axogen/blob/main/website/blog/2025-07-26-i-built-a-typescript-native-config-system-because-env-files-drive-me-crazy.mdx

This command formats the Rust code within the server directory using `cargo fmt`. It ensures Rust code in the server module follows standard formatting guidelines.

```shell
cd server && cargo fmt --all
```