Ask Forge Configuration Reference

Config File

Ask Forge stores its configuration in ~/.schemasmith/askforge.json — the single file read by the CLI, the MCP server, and every tool. A default config is created automatically on first run if one does not exist. The resolved path depends on your platform:

Windows: C:\Users\<username>\.schemasmith\askforge.json
macOS / Linux: ~/.schemasmith/askforge.json

The file has three top-level sections:

Complete askforge.json Example

{
  "llm": {
    "active": "anthropic",
    "providers": {
      "ollama-local": {
        "type": "ollama",
        "endpoint": "http://localhost:11434",
        "model": "llama3:8b"
      },
      "anthropic": {
        "type": "anthropic",
        "apiKey": "${ANTHROPIC_API_KEY}",
        "model": "claude-sonnet-4-20250514"
      },
      "openai": {
        "type": "openAI",
        "apiKey": "${OPENAI_API_KEY}",
        "model": "gpt-4o"
      }
    }
  },
  "connections": {
    "sqlserver": {
      "server": "localhost",
      "port": 1433,
      "database": "MyDB",
      "user": "sa",
      "password": "${MSSQL_PASSWORD}"
    },
    "postgresql": {
      "server": "localhost",
      "port": 5432,
      "database": "mydb",
      "user": "postgres",
      "password": "${PGSQL_PASSWORD}"
    },
    "mysql": {
      "server": "localhost",
      "port": 3306,
      "database": "mydb",
      "user": "root",
      "password": "${MYSQL_PASSWORD}"
    }
  },
  "agent": {
    "trustLevel": "assistant",
    "autoExecute": true,
    "confirmTier3": true,
    "confirmTier4": true,
    "confirmationLevel": "always",
    "maxToolIterations": 10,
    "contextLevel": "standard",
    "showToolCalls": true,
    "autoSaveSession": false,
    "resumeLastSession": false,
    "sessionDirectory": "~/.schemasmith/sessions",
    "maxConversationTurns": 20
  }
}

llm

Controls which LLM backend Ask Forge uses. Define multiple named providers and set active to switch between them. Set active to null to disable LLM integration entirely (tools still work).

See LLM Providers

connections

Per-platform database connection settings (SQL Server, PostgreSQL, MySQL). Passwords support ${ENV_VAR} substitution to keep secrets out of the file.

See Database Connections

agent

Controls the agentic tool-execution loop, trust boundaries, confirmation prompts, context depth, and session management.

See the agent properties table

Agent Properties

Property	Type	Default	Description
`trustLevel`	string	`"assistant"`	Permission level: `observer` (read-only), `assistant` (read + safe writes), or `operator` (full access).
`autoExecute`	bool	`true`	Allow tools to run without manual approval, within the current trust level.
`confirmTier3`	bool	`true`	Always prompt before Modify (Tier 3) tools, even if `autoExecute` is true.
`confirmTier4`	bool	`true`	Always prompt before External (Tier 4) tools, even if `autoExecute` is true.
`confirmationLevel`	string	`"always"`	Confirmation policy for direct CLI tool commands: `always`, `external` (only Tier 4), or `never`.
`maxToolIterations`	int	`10`	Maximum tool calls per conversation turn. Prevents infinite loops.
`contextLevel`	string	`"standard"`	Schema context depth: `minimal` (table names only), `standard` (current table full, others summarized), `full` (all tables in detail). Higher levels consume more tokens.
`showToolCalls`	bool	`true`	Display tool invocations and parameters in output.
`autoSaveSession`	bool	`false`	Automatically save the conversation to disk on exit.
`resumeLastSession`	bool	`false`	Prompt to resume the previous session on startup.
`sessionDirectory`	string	`"~/.schemasmith/sessions"`	Directory where saved sessions are stored.
`maxConversationTurns`	int	`20`	Maximum conversation history kept in memory. Older turns are dropped to stay within LLM context limits.

Precedence

Configuration values are resolved in priority order. When a value is set at multiple levels, the highest-priority source wins.

CLI Parameters
Explicit command-line flags (e.g., --product, --template, or per-tool flags like --server)
Highest
Environment Variables
SCHEMASMITH_* variables (e.g., SCHEMASMITH_LLM_PROVIDER, SCHEMASMITH_LLM_ACTIVE)
High
Config File
Values in ~/.schemasmith/askforge.json
Normal
Built-in Defaults
Sensible defaults for all settings (e.g., trust level = assistant)
Lowest

Example: Passing --server to a manage-connection command overrides the server stored in the config file for that platform, for that invocation only.

Environment Variables

Ask Forge reads SCHEMASMITH_* environment variables for configuration overrides. Each variable takes precedence over the corresponding config file property — handy for CI/CD pipelines and containers where you want configuration without a config file.

LLM Quick Setup

These variables configure a provider without editing the config file. When SCHEMASMITH_LLM_PROVIDER is set, Ask Forge creates a synthetic provider named env-override and activates it, bypassing the config file's llm section entirely.

Variable	Purpose	Overrides
`SCHEMASMITH_LLM_ACTIVE`	Select the active LLM provider by name	`llm.active`
`SCHEMASMITH_LLM_PROVIDER`	Provider type (e.g., `anthropic`, `openAI`, `ollama`)	Creates `env-override` provider
`SCHEMASMITH_LLM_API_KEY`	API key for the provider	Used with `SCHEMASMITH_LLM_PROVIDER`
`SCHEMASMITH_LLM_MODEL`	Model name	Used with `SCHEMASMITH_LLM_PROVIDER`
`SCHEMASMITH_LLM_ENDPOINT`	Endpoint URL	Used with `SCHEMASMITH_LLM_PROVIDER`

Provider-Specific Overrides

These create or override a single named provider, leaving the rest of the llm section intact.

Variable	Purpose
`SCHEMASMITH_OLLAMA_ENDPOINT`	Override the Ollama endpoint URL
`SCHEMASMITH_OLLAMA_MODEL`	Override the Ollama model name
`SCHEMASMITH_OPENAI_API_KEY`	Configure the OpenAI provider
`SCHEMASMITH_OPENAI_MODEL`	Override the OpenAI model (default: `gpt-4o`)
`SCHEMASMITH_ANTHROPIC_API_KEY`	Configure the Anthropic provider
`SCHEMASMITH_ANTHROPIC_MODEL`	Override the Anthropic model (default: `claude-sonnet-4-20250514`)

License

Ask Forge requires a valid license to run. It looks for a file named SchemaSmith License.lic in its install directory, then up the directory tree and on your PATH. Set SCHEMASMITH_LICENSE to the license file or its directory to load it from anywhere else:

Variable	Purpose
`SCHEMASMITH_LICENSE`	Path to the license file or directory.

Secret Substitution

API keys and passwords in askforge.json support ${ENV_VAR} syntax for environment variable substitution. Instead of storing raw secrets in the config file, reference environment variables:

API Key Example

{
  "llm": {
    "providers": {
      "anthropic": {
        "type": "anthropic",
        "apiKey": "${ANTHROPIC_API_KEY}",
        "model": "claude-sonnet-4-20250514"
      }
    }
  }
}

Database Password Example

{
  "connections": {
    "sqlserver": {
      "server": "localhost",
      "database": "MyDB",
      "user": "sa",
      "password": "${MSSQL_PASSWORD}"
    }
  }
}

If a referenced environment variable is not set, Ask Forge reports a configuration error at startup. Set values in your shell profile, a .env file loaded by your shell, or a secrets manager.

Database Connections

The connections section stores per-platform database settings used by External (Tier 4) tools when they run SchemaTongs, SchemaQuench, or DataTongs. Edit the config file directly, or manage connections from the CLI with manage-connection — one command handles the full lifecycle through its --action parameter.

CLI Commands

# Set a connection (action=set)
ask-forge manage-connection --action set \
  --platform sqlserver --server localhost --port 1433 \
  --database MyDB --user sa --password "${MSSQL_PASSWORD}"

ask-forge manage-connection --action set \
  --platform postgresql --server localhost --port 5432 \
  --database mydb --user postgres --password "${PGSQL_PASSWORD}"

ask-forge manage-connection --action set \
  --platform mysql --server localhost --port 3306 \
  --database mydb --user root --password "${MYSQL_PASSWORD}"

# Clear a connection (action=clear)
ask-forge manage-connection --action clear --platform sqlserver

# View current config (passwords masked)
ask-forge show-config

Config File Format

{
  "connections": {
    "sqlserver": {
      "server": "localhost",
      "port": 1433,
      "database": "MyDB",
      "user": "sa",
      "password": "${MSSQL_PASSWORD}"
    }
  }
}

{
  "connections": {
    "postgresql": {
      "server": "localhost",
      "port": 5432,
      "database": "mydb",
      "user": "postgres",
      "password": "${PGSQL_PASSWORD}"
    }
  }
}

{
  "connections": {
    "mysql": {
      "server": "localhost",
      "port": 3306,
      "database": "mydb",
      "user": "root",
      "password": "${MYSQL_PASSWORD}"
    }
  }
}

Platform keys are sqlserver, postgresql, and mysql.

Tool Discovery

SchemaSmith tools are found automatically

Ask Forge locates the SchemaSmith CLI tools (SchemaTongs, SchemaQuench, DataTongs) on its own — there is no per-tool path to configure. It searches its own install directory, the SchemaSmithPath environment variable, the standard Program Files\SchemaSmith location, and your system PATH, in that order. If the tools live somewhere non-standard, set SchemaSmithPath to the install directory.

Configuration Reference