Configuration Reference

Where Ask Forge keeps its settings, what each part of the file controls, how to store a database connection for each engine, and which environment variables it reads.

By the SchemaSmith Team · Last reviewed

Ask Forge configuration reference

Credentials are scoped to the settings file they were configured in.

Config File

Ask Forge stores its configuration in ~/.schemasmith/askforge.json, which on Windows is C:\Users\<username>\.schemasmith\askforge.json. By default it is the one file the CLI, the MCP server, and its tools all use.

What the file holds

The file has three top-level sections, plus an optional logHygiene block you add by hand:

Section What it holds
llm The LLM providers for conversational mode, and which one is active. LLM Providers covers it.
connections One database connection per platform, used by the Deploy tools. See Connections.
agent How the conversational agent behaves, the CLI's confirmation prompts, and saved sessions. See Agent and Session Settings.
logHygiene Names of your own secrets to mask. See Masking Your Own Secret Names.

When the file is written

The file does not have to exist, and a missing one is normal. Ask Forge does not create it at startup. It is written the first time you save a setting, such as an LLM provider, a database connection, or an agent setting.

Every save reads the whole file, changes the part you asked for, and writes the whole file back. Settings you did not change are kept, including a logHygiene block. Comments are dropped, and the logHygiene block can move to the end.

If the file cannot be read

An empty file is treated the same way as a missing one.

A file that exists but cannot be parsed stops ask-forge at launch with an error naming the file and the parse failure, and exits with code 1. It does not fall back to defaults. Every save rewrites the whole file, so carrying on would mean the next save overwrites your configuration with everything except the one section being changed, and the file also holds the only references that can find your credentials in the operating system's credential store.

Fix the JSON, or move the file aside so the next save writes a fresh one. The file is read leniently, so comments, single quotes and unquoted property names are accepted. Common causes are an unescaped backslash in a Windows path and a missing quote.

A settings file for a scripted run

--config <path> makes the CLI read and write settings at that path instead of ~/.schemasmith/askforge.json. It plays the same role for ask-forge that --ConfigFile plays for SchemaQuench, SchemaTongs, and DataTongs. Point it at a settings file committed alongside your schema package, and a CI job reads that file rather than whatever is in the build agent's home directory. The override applies to every setting Ask Forge reads or writes, including LLM providers, connections, and agent settings:

ask-forge --config .\ci\askforge.json review-schema --product .\MyProduct
ask-forge --config ./ci/askforge.json review-schema --product ./MyProduct

The MCP server has no such option. It always reads ~/.schemasmith/askforge.json.

Ask Forge also keeps a small record of the session directory beside the settings file in use: askforge.session-directory.json next to askforge.json, or next to the file --config names, under that file's own name. Your settings file is never rewritten to store it. If you keep the settings file in source control, add *.session-directory.json to that repository's ignore list. The record is disposable.

Connections

The connections section holds the details the Deploy tools use to run SchemaTongs, SchemaQuench, or DataTongs against a database. There is one connection per platform, keyed by platform. A run uses the connection for the platform of the package you are working on. MariaDB has its own connection, separate from MySQL's. SchemaShears works from files, so it needs no connection.

Pick your engine to see its key and an example:

The key is sqlserver, and the platform name on the command line is SqlServer. The default port is 1433.

{
  "connections": {
    "sqlserver": {
      "server": "localhost",
      "port": 1433,
      "database": "MyDatabase",
      "user": "sa",
      "password": "${SQLSERVER_PASSWORD}",
      "connectionProperties": {
        "TrustServerCertificate": "true"
      }
    }
  }
}

For Windows Authentication, set "integratedSecurity": true instead of a user and password. It supersedes any configured user and password. Connection properties take SQL Server's keys, such as TrustServerCertificate, Encrypt, and ApplicationIntent.

The key is postgresql, and the platform name on the command line is PostgreSQL. The default port is 5432.

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

PostgreSQL requires explicit credentials. Connection properties take Npgsql's keys, such as SslMode, Pooling, and Timeout.

The key is mysql, and the platform name on the command line is MySQL. The default port is 3306.

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

MySQL requires explicit credentials. Connection properties take MySqlConnector's keys, such as SslMode, ConnectionTimeout, and AllowPublicKeyRetrieval.

The key is mariadb, and the platform name on the command line is MariaDb. The default port is 3306.

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

MariaDB requires explicit credentials. Its connection is separate from MySQL's, so set it even when a MySQL connection already exists. Connection properties take keys such as SslMode.

Connection fields

Field Description
server Database server hostname or IP.
port Port number. Optional: without it, the platform default is used.
database Database name. SchemaTongs and DataTongs use it; SchemaQuench reads its target databases from the schema package instead.
user Username.
password A ${ENV_VAR} reference, resolved when the connection is used. A literal password is not stored here: see Credential Storage.
protectedPassword Written by Ask Forge: an opaque token issued by your operating system's credential store. It is not the password, and it is meaningless outside the store that issued it.
integratedSecurity SQL Server only. Use Windows Authentication, superseding any configured user and password.
connectionProperties Additional connection string properties.

Whatever you put in connectionProperties is appended to the connection string for that platform's client library. The driver's own documentation has the full list.

Platform keys are normalized to sqlserver, postgresql, mysql, and mariadb. Legacy keys (mssql, pgsql) are migrated automatically.

Set, update, and clear a connection

From the command line, manage-connection covers the full lifecycle through its --action parameter. Put a ${ENV_VAR} password in single quotes so your shell passes it through as written:

# Set a connection
ask-forge manage-connection --action set --platform SqlServer `
  --server localhost --database MyDb --user sa `
  --password '${SQLSERVER_PASSWORD}'

# Change one field and keep the rest
ask-forge manage-connection --action set --platform SqlServer `
  --database StagingDB

# Remove the connection
ask-forge manage-connection --action clear --platform SqlServer
# Set a connection
ask-forge manage-connection --action set --platform SqlServer \
  --server localhost --database MyDb --user sa \
  --password '${SQLSERVER_PASSWORD}'

# Change one field and keep the rest
ask-forge manage-connection --action set --platform SqlServer \
  --database StagingDB

# Remove the connection
ask-forge manage-connection --action clear --platform SqlServer

You do not need the full connection to change one field. Run set again with only the fields you want to change, and the existing values are kept. --integrated-security turns on Windows Authentication for a SQL Server connection, and --connection-properties takes the properties as a JSON object.

Ask an AI assistant to connect to your database. manage_connection is not in the server's curated tool list, so the assistant reaches it through schemasmith_execute_tool, passing action: "set" and your connection details as the arguments for manage_connection.

show-config and list-connections show what is configured, with passwords masked.

Credential Storage

Two kinds of credential reach askforge.json: LLM API keys and database connection passwords. Ask Forge never writes either secret value to the file.

A literal value goes to your operating system's credential store. The config file records only an opaque token: protectedApiKey on a provider, and protectedPassword on a connection:

Platform Where the credential goes
Windows The Data Protection API (DPAPI) at CurrentUser scope, recoverable only by the same Windows user on the same machine.
macOS The login Keychain.
Linux The Secret Service (libsecret, GNOME Keyring, KWallet), through secret-tool.

Where no credential store is available, nothing is saved. A headless CI runner, a container, or a Linux host with no keyring is the common case. Ask Forge does not fall back to a weaker scheme: the value you supplied works for the current session, and Ask Forge tells you it was not saved. The same happens on Linux with a value longer than 8,192 bytes, which is more than secret-tool stores whole.

Use ${ENV_VAR} on those hosts. The reference is written to the file as you typed it, and the value is read from the environment each time the credential is used, so the value is never stored. It is the recommended route for CI generally.

Credentials are scoped to the settings file they were configured in. A key saved while running under --config ./ci/askforge.json is filed separately from one saved against ~/.schemasmith/askforge.json. Copying a config file to another machine does not bring the credential along. The token there resolves to nothing, so you supply the value again.

Deleting a provider or clearing a connection also removes its stored credential. Switching a literal value to a ${ENV_VAR} reference removes it too, because there is no longer a literal to keep. Removing a stored credential is best effort. Where it matters, such as a shared machine or a credential you are rotating because it leaked, check the store yourself.

Agent and Session Settings

The agent section controls the AI agent's behavior in conversational mode, the CLI's confirmation prompts for direct tool commands, and saved sessions. The MCP server does not read it. Every setting is optional, and a setting the file leaves out takes its default. Trust Levels explains the trust and confirmation settings.

{
  "agent": {
    "trustLevel": "assistant",
    "confirmationLevel": "always",
    "contextLevel": "standard",
    "autoSaveSession": false
  }
}
Setting Default Description
trustLevel assistant Maximum tool tier for the AI agent: observer, assistant, or operator.
autoExecute false Answer "yes" to a confirmation when there is no one to ask. ask-forge itself ignores it.
confirmTier3 true Prompt before the agent runs a Modify (Tier 3) tool.
confirmTier4 true Prompt before the agent runs an External (Tier 4) tool.
confirmationLevel always CLI confirmation for direct tool commands: always, external, or never. --yes skips it.
contextLevel standard How much schema context goes into prompts: minimal (names only), standard (current table in detail, others summarized), full (every detail).
showToolCalls true Display tool invocations in output for transparency.
maxToolIterations 10 Maximum rounds of tool calls in one agent turn; each round can run several tools. A turn that reaches the limit stops.
maxConversationTurns 20 Conversation history length.
autoSaveSession false Save the conversation automatically after every reply.
resumeLastSession false Prompt to resume the last session on startup.
sessionDirectory ~/.schemasmith/sessions Where sessions are read from and written to.

Changing a setting from the REPL

In the REPL, config agent shows the agent settings, and config agent <property> <value> changes one and saves it:

config agent contextLevel full

That covers trustLevel, autoExecute, confirmTier3, confirmTier4, maxToolIterations, contextLevel, showToolCalls, autoSaveSession, and resumeLastSession. Set confirmationLevel, maxConversationTurns, and sessionDirectory in the file.

Session settings

When enabled, sessions keep the conversation history and product and template context, so you can pick up where you left off. Named sessions (session save <name>) are written to the session directory; auto-saves go to its auto/ subfolder, which keeps the ten most recent. Console & Commands covers the session commands.

sessionDirectory accepts an absolute path or a ~/... path. Ask Forge creates the directory if it does not exist. A relative path is resolved against the directory you launched ask-forge from, so prefer an absolute one. Only the settings file sets it, so edit askforge.json and restart. config and config agent both show the directory in use.

Changing it does not move your existing sessions. Nothing is copied or deleted, and Ask Forge reads only the new directory. session list and config both tell you when earlier sessions are still somewhere you are no longer reading. To bring them across, copy the .json files (and the auto/ subfolder) yourself, or point sessionDirectory back at that directory.

A saved session is a transcript

Treat it as sensitive. Values that Ask Forge passes to a tool are masked before they are written: a password given to manage_connection is stored as ***. What you type is not masked. Keep credentials out of the conversation and supply them as tool arguments or environment variables. To end the exposure, delete the files: session delete <name> for a named session, or remove the auto/ subfolder of the session directory for the auto-saves.

Masking Your Own Secret Names

Ask Forge masks a value whose name looks secret, such as a password, a token, an API key, or a connection string, wherever it shows one: tool parameters in its log, confirmation prompts and saved sessions, connection listings, and the token values manage_tokens displays. The built-in name patterns cannot know every name you give a secret, so Ask Forge honors the same LogHygiene block a SchemaSmith CLI tool's settings file takes:

{
  "logHygiene": {
    "scrubTokens": [ "DeployKey" ],
    "scrubPatterns": [ "*Salt*" ],
    "allowTokens": [ "TokenCount" ],
    "logTokens": false
  }
}
  • scrubTokens: exact names to mask, ignoring case.
  • scrubPatterns: names to mask wherever the pattern's text appears in them (*Salt* masks UserSalt).
  • allowTokens: names to show even though a built-in pattern matches them (TokenCount would otherwise match Token).
  • logTokens: false makes manage_tokens show token names only, never their values. The default, true, shows values, masked as above.

Both the ask-forge CLI and the MCP server read the block when they start (the CLI reads the file --config names, when you give one), so restart them after changing it. There is no config command for the block; edit the file.

The loaded product's SchemaQuench settings count too: SchemaQuench.settings.json in the product's folder, read each time a product is loaded. When more than one block applies, the strictest wins.

The rules themselves, and the built-in patterns, are the Community tools' own: see Sensitive value masking.

Environment Variables

Ask Forge reads these environment variables:

Variable Read by What it does
SCHEMASMITH_PRODUCT_PATH CLI and MCP server Preloads a schema package at launch. --product-path takes precedence over it, and on the CLI so does --product.
SchemaSmithPath The Deploy tools A folder to search for the SchemaSmith Community tools, after Ask Forge's own folder. Getting Started gives the full search order.
SCHEMASMITH_LICENSE CLI and MCP server The license file, or the folder that holds it. See License File.
ASKFORGE_LICENSE CLI and MCP server An older name for SCHEMASMITH_LICENSE. It is still read, after that one.
SCHEMASMITH_LLM_ACTIVE, SCHEMASMITH_LLM_PROVIDER, SCHEMASMITH_LLM_ENDPOINT, SCHEMASMITH_LLM_MODEL, SCHEMASMITH_LLM_API_KEY CLI Select or configure an LLM provider without editing the file. See LLM Providers.
SCHEMASMITH_OLLAMA_ENDPOINT, SCHEMASMITH_OLLAMA_MODEL, SCHEMASMITH_OPENAI_API_KEY, SCHEMASMITH_OPENAI_MODEL, SCHEMASMITH_ANTHROPIC_API_KEY, SCHEMASMITH_ANTHROPIC_MODEL CLI Create or override a named provider. See LLM Providers.

The LLM variables take precedence over the config file.

Connections in CI

There are no environment variables for a database connection. Commit a settings file whose connection's password is a ${ENV_VAR} reference, and point the run at it with --config; the reference is resolved when the connection is used, and the value is never stored:

{
  "connections": {
    "sqlserver": {
      "server": "db-server.internal",
      "database": "MyApp",
      "user": "deploy_user",
      "password": "${DB_DEPLOY_PASSWORD}"
    }
  }
}

Shape. Strengthen. Succeed.

Free schema-as-code for SQL Server, PostgreSQL, MySQL, and MariaDB.

The source is on GitHub for anyone to read.

Get Started on GitHub