Settings
Every setting of the vlatte command, as vlatte --help lists it: its flag, its environment variable and its key in a .vlatterc file. See Configuration for the order sources apply in and how values are written.
Servers made in Go read the same settings from a .vlatterc file and VLATTE_* variables, except those of the command only, such as https and admin: see Configuration.
txt
Settings:
--admin
Serve the admin API, on an HTTP server of its own. Default: true.
env VLATTE_ADMIN, file key admin
--admin-addr string
Address the admin API listens on: host:port, :port or port. Empty picks a random local port.
env VLATTE_ADMIN_ADDR, file key admin.addr
--admin-dir string
Directory of the files that keep the mocks the admin API adds across restarts, which only the server loads: keep it out of mock_files. Relative paths start at root_dir, and {workdir} at workdir. Empty keeps them in memory.
env VLATTE_ADMIN_DIR, file key admin.dir
--admin-docs-version string
Version of Scalar, such as 1.80.0, that the documentation page of the admin APIs, at /docs, loads instead of the one vlatte pins, which it checks against its hash. Empty is the pinned one.
env VLATTE_ADMIN_DOCS_VERSION, file key admin.docs_version
--admin-auth-username string
Username the admin APIs ask every request for, but their probes, with admin.auth.password: HTTP Basic authentication, which browsers show a sign-in prompt for. Serve them over TLS beyond the local host.
env VLATTE_ADMIN_AUTH_USERNAME, file key admin.auth.username
VLATTE_ADMIN_AUTH_PASSWORD string
Password of admin.auth.username. Or admin.auth.password_file.
file key admin.auth.password; no flag, as the command line shows to every user of the host
--admin-auth-password-file string
File that holds the password of admin.auth.username, such as a Docker or Kubernetes secret. A trailing line break isn't part of it.
env VLATTE_ADMIN_AUTH_PASSWORD_FILE, file key admin.auth.password_file
VLATTE_ADMIN_AUTH_TOKEN string
Bearer token the admin APIs ask every request for, but their probes: in Authorization: Bearer, or as the password of Basic, with any username, from a browser. Generate one with openssl rand -hex 32. Or admin.auth.token_file.
file key admin.auth.token; no flag, as the command line shows to every user of the host
--admin-auth-token-file string
File that holds the bearer token of the admin APIs, such as a Docker or Kubernetes secret. A trailing line break isn't part of it.
env VLATTE_ADMIN_AUTH_TOKEN_FILE, file key admin.auth.token_file
--admin-tls-cert string
Certificate file, PEM, the admin APIs serve HTTPS with, with admin.tls.key.
env VLATTE_ADMIN_TLS_CERT, file key admin.tls.cert
--admin-tls-key string
Private key file, PEM, of admin.tls.cert.
env VLATTE_ADMIN_TLS_KEY, file key admin.tls.key
--mcp
Serve the admin API's operations to AI agents over MCP: at POST /mcp of the admin API, and over stdio with vlatte mcp. Default: true.
env VLATTE_MCP, file key mcp
--webhook-timeout duration
How long a webhook without a timeout of its own waits for its answer, for HTTP and gRPC mocks: milliseconds or a Go duration (1.5s). 0 uses 10s.
env VLATTE_WEBHOOK_TIMEOUT, file key webhook.timeout
--kv-file string
CSV file to fill the key-value store with, which templates of HTTP and gRPC mocks read as .KV: the header key,value, then a row for each key. Changes to the store stay in memory, never in the file. Empty starts the store empty.
env VLATTE_KV_FILE, file key kv.file
--grpc-admin
Serve the admin API of the gRPC server, on an HTTP server of its own. Default: true.
env VLATTE_GRPC_ADMIN, file key grpc.admin
--grpc-admin-addr string
Address the gRPC server's admin API listens on: host:port, :port or port. Empty picks a random local port.
env VLATTE_GRPC_ADMIN_ADDR, file key grpc.admin.addr
--grpc-admin-dir string
Directory of the files that keep the mocks the gRPC server's admin API adds across restarts, which only the server loads: keep it out of grpc.mock_files. Relative paths start at grpc.root_dir, and {workdir} at workdir. Empty keeps them in memory.
env VLATTE_GRPC_ADMIN_DIR, file key grpc.admin.dir
-c, --config string
Config file to load, instead of looking up .vlatterc.{json,yaml,yml} in . and testdata.
env VLATTE_CONFIG, file key config
-n, --name string
Server name, shown in logs. It names the folder of the server's files in testdata/vlatte, unless workdir is set: a path inside it, which doesn't start with _.
env VLATTE_NAME, file key name
-a, --addr string
Address to listen on: host:port, :port or port. Empty picks a random local port.
env VLATTE_ADDR, file key addr
--root-dir string
Directory that relative mock file patterns and recording paths start at.
env VLATTE_ROOT_DIR, file key root_dir
--workdir string
Directory of the server's own files: its mock files, recordings, admin mocks and journal. A path setting that starts with {workdir} starts there. Relative paths start at root_dir. Default: testdata/vlatte, or testdata/vlatte/<name> for a named server.
env VLATTE_WORKDIR, file key workdir
--mock-files list
Glob patterns of the mock files to load on start. Default: {workdir}/_mocks/*mock.yaml,{workdir}/_mocks/*mock.yml,{workdir}/_mocks_recorded/*.mock.json,{workdir}/_mocks_recorded/*.mock.yaml,{workdir}/_mocks_recorded/*.mock.yml.
env VLATTE_MOCK_FILES, file key mock_files
--no-match-status-code int
Status code of the response to a request that matches no mock. Default: 418.
env VLATTE_NO_MATCH_STATUS_CODE, file key no_match_status_code
--no-match-format name
Format of the response to a request that matches no mock. auto follows its Accept header. One of: auto, text, markdown, json, problem. Default: auto.
env VLATTE_NO_MATCH_FORMAT, file key no_match_format
--error-status-code int
Status code of the response when serving a request fails, such as a reply that fails. Default: 418.
env VLATTE_ERROR_STATUS_CODE, file key error_status_code
--https
Serve HTTPS instead of HTTP. Only the vlatte command reads it.
env VLATTE_HTTPS, file key https
--colors
Use colors in debug logs. Default: true.
env VLATTE_COLORS, file key colors
--debug
Print descriptive logs for each request, instead of structured ones.
env VLATTE_DEBUG, file key debug
--debug-headers
Add debug headers, such as VLatte-Matched-Mock-Id, to each answer. VLatte-Error stays either way. Default: true.
env VLATTE_DEBUG_HEADERS, file key debug_headers
--near-misses
List the mocks closest to a request no mock matched in its answer. It runs the matchers matching never reached. Default: true.
env VLATTE_NEAR_MISSES, file key near_misses
--tls-cert string
TLS certificate file. Requires tls.key.
env VLATTE_TLS_CERT, file key tls.cert
--tls-key string
TLS private key file. Requires tls.cert.
env VLATTE_TLS_KEY, file key tls.key
--tls-ca string
File of the CA certificates that client certificates must be signed by (mutual TLS). Requires tls.cert and tls.key.
env VLATTE_TLS_CA, file key tls.ca
--log-level name
Log level. One of: trace, debug, info, warn, error, fatal, panic, none, disabled. Default: info.
env VLATTE_LOG_LEVEL, file key log.level
--log-verbosity name
How much of each request and response to log. One of: basic, header, body. Default: header.
env VLATTE_LOG_VERBOSITY, file key log.verbosity
--log-max-body-size int
Bodies larger than this many bytes aren't logged. 0 logs bodies of any size.
env VLATTE_LOG_MAX_BODY_SIZE, file key log.max_body_size
--log-pretty
Human-friendly console logs instead of JSON. Default: true.
env VLATTE_LOG_PRETTY, file key log.pretty
--cors
Enable CORS.
env VLATTE_CORS, file key cors
--cors-allowed-origin string
Allowed origins, comma-separated. * allows any. Default: *.
env VLATTE_CORS_ALLOWED_ORIGIN, file key cors.allowed_origin
--cors-allow-credentials
Send Access-Control-Allow-Credentials: true. With *, the origin of the request is allowed.
env VLATTE_CORS_ALLOW_CREDENTIALS, file key cors.allow_credentials
--cors-allowed-methods string
Allowed methods, comma-separated. * allows the method a preflight request asks for. Default: GET,POST,HEAD,PUT,DELETE,PATCH.
env VLATTE_CORS_ALLOWED_METHODS, file key cors.allowed_methods
--cors-allowed-headers string
Allowed headers, comma-separated. Empty or * allows the headers a preflight request asks for.
env VLATTE_CORS_ALLOWED_HEADERS, file key cors.allowed_headers
--cors-expose-headers string
Headers exposed to browsers, comma-separated.
env VLATTE_CORS_EXPOSE_HEADERS, file key cors.expose_headers
--cors-max-age int
Seconds browsers may cache a preflight response. -1 omits Access-Control-Max-Age. Default: 0.
env VLATTE_CORS_MAX_AGE, file key cors.max_age
--cors-success-status-code int
Status code of the response to a preflight request. Browsers fail a preflight answered with a status other than 2xx. Default: 204.
env VLATTE_CORS_SUCCESS_STATUS_CODE, file key cors.success_status_code
--proxy
Proxy the requests that match no mock to their original host.
env VLATTE_PROXY, file key proxy
--proxy-via string
URL of a proxy to send proxied requests through.
env VLATTE_PROXY_VIA, file key proxy.via
--proxy-timeout duration
How long to wait for the response headers of a proxied request: milliseconds or a Go duration (1.5s). 0 waits forever. Default: 30s.
env VLATTE_PROXY_TIMEOUT, file key proxy.timeout
--proxy-ssl-verify
Verify the TLS certificates of proxied servers.
env VLATTE_PROXY_SSL_VERIFY, file key proxy.ssl_verify
--proxy-intercept
Serve the HTTPS of CONNECT tunnels with certificates signed by proxy.ca_cert, so mocks answer it. Requires proxy.ca_cert and proxy.ca_key.
env VLATTE_PROXY_INTERCEPT, file key proxy.intercept
--proxy-ca-cert string
Certificate file of the CA that signs the certificates proxy.intercept serves, which clients must trust. Requires proxy.ca_key.
env VLATTE_PROXY_CA_CERT, file key proxy.ca_cert
--proxy-ca-key string
Private key file of proxy.ca_cert. Requires proxy.ca_cert.
env VLATTE_PROXY_CA_KEY, file key proxy.ca_key
--proxy-all
Proxy the requests no mock matches, but those the forward proxy sends on, to proxy_all.target.
env VLATTE_PROXY_ALL, file key proxy_all
--proxy-all-target string
URL of the server to forward requests to. Its path and query come before the request's.
env VLATTE_PROXY_ALL_TARGET, file key proxy_all.target
--proxy-all-remove-request-headers list
Headers removed from the forwarded request.
env VLATTE_PROXY_ALL_REMOVE_REQUEST_HEADERS, file key proxy_all.remove_request_headers
--proxy-all-trim-prefix string
Prefix of whole segments removed from the request path, before the target's path is added.
env VLATTE_PROXY_ALL_TRIM_PREFIX, file key proxy_all.trim_prefix
--proxy-all-trim-suffix string
Text removed from the end of the request path, such as an extension, before the target's path is added.
env VLATTE_PROXY_ALL_TRIM_SUFFIX, file key proxy_all.trim_suffix
--proxy-all-timeout duration
How long to wait for the target's response headers, connecting and sending the request included: milliseconds or a Go duration (1.5s). 0 waits forever. Default: 30s.
env VLATTE_PROXY_ALL_TIMEOUT, file key proxy_all.timeout
--proxy-all-ssl-verify
Verify the TLS certificate of the target. Off by default.
env VLATTE_PROXY_ALL_SSL_VERIFY, file key proxy_all.ssl_verify
--proxy-all-x-forwarded
Set X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Proto on the forwarded request, with the client's address, host and scheme.
env VLATTE_PROXY_ALL_X_FORWARDED, file key proxy_all.x_forwarded
--proxy-all-preserve-host
Send the target the Host the client asked for, in place of the target's.
env VLATTE_PROXY_ALL_PRESERVE_HOST, file key proxy_all.preserve_host
--record
Record proxied requests and their responses as mock files, from start to close.
env VLATTE_RECORD, file key record
--record-dir string
Directory of the recordings. Relative paths start at root_dir, and {workdir} at workdir. Default: {workdir}/_mocks_recorded.
env VLATTE_RECORD_DIR, file key record.dir
--record-format string
Format of the recorded mock files: json, yaml, yml. Default: json.
env VLATTE_RECORD_FORMAT, file key record.format
--record-target string
Server to record, such as https://api.example.com: the requests the recording takes go to it, before any mock.
env VLATTE_RECORD_TARGET, file key record.target
--record-skip-ssl-verify
Skip the verification of the TLS certificate of record.target, such as for a self-signed one.
env VLATTE_RECORD_SKIP_SSL_VERIFY, file key record.skip_ssl_verify
--record-methods list
Methods of the requests the recording takes. Empty takes every method.
env VLATTE_RECORD_METHODS, file key record.methods
--record-paths list
Glob patterns of the paths of the requests the recording takes, such as /v1/*, where * matches / too. Empty takes every path.
env VLATTE_RECORD_PATHS, file key record.paths
--record-request-headers list
Request headers recordings match: the first value each had, or its absence.
env VLATTE_RECORD_REQUEST_HEADERS, file key record.request_headers
--record-exclude-response-headers list
Response headers recordings leave out. A list replaces the default; an empty one keeps every header. Default: Set-Cookie.
env VLATTE_RECORD_EXCLUDE_RESPONSE_HEADERS, file key record.exclude_response_headers
--record-body-files
Write each recorded response body to a file of its own, instead of inline.
env VLATTE_RECORD_BODY_FILES, file key record.body_files
--record-max-inline-body int
Bytes of a body kept in memory while it is recorded: a larger one goes to a file as it streams. Text bodies kept in memory are written inline. 0 uses the default. Default: 1048576.
env VLATTE_RECORD_MAX_INLINE_BODY, file key record.max_inline_body
--record-max-body-size int
Calls with a larger response body, in bytes, aren't recorded. 0 uses the default; a negative value means no limit. Default: 1073741824.
env VLATTE_RECORD_MAX_BODY_SIZE, file key record.max_body_size
--record-repeats name
What a recording keeps of a request that comes again: every response, in order, or the first one. One of: sequence, first. Default: sequence.
env VLATTE_RECORD_REPEATS, file key record.repeats
--record-include-mocked
Record the answers of mocks too, not only proxied ones.
env VLATTE_RECORD_INCLUDE_MOCKED, file key record.include_mocked
--journal
Keep a journal of the requests the server serves, of every outcome.
env VLATTE_JOURNAL, file key journal
--journal-dir string
Directory of the journal's files, kept across restarts. Relative paths start at root_dir, and {workdir} at workdir. Empty keeps them in a temporary directory, removed when the server stops.
env VLATTE_JOURNAL_DIR, file key journal.dir
--journal-max-entries int
How many requests the journal keeps, the newest. 0 keeps them all. Default: 10000.
env VLATTE_JOURNAL_MAX_ENTRIES, file key journal.max_entries
--journal-max-body-size int
How many bytes of a request's body the journal keeps. 0 keeps whole bodies. Default: 1048576.
env VLATTE_JOURNAL_MAX_BODY_SIZE, file key journal.max_body_size
--template-env list
Environment variables templates may read with env, by exact name. Templates read none without it.
env VLATTE_TEMPLATE_ENV, file key template.env
--template-keys list
Keys templates sign tokens with, jwt, and publish, jwks: kid=ALG generates one at start, such as google-1=RS256, and kid=ALG:path reads a PEM private key, relative paths starting at root_dir.
env VLATTE_TEMPLATE_KEYS, file key template.keys
--outbound-allow list
Address ranges the server may connect to, in CIDR form, such as 10.1.0.0/16: proxied requests, the recording target, the forward proxy and webhooks reach no other address. Empty allows every address.
env VLATTE_OUTBOUND_ALLOW, file key outbound.allow
--outbound-deny list
Address ranges the server never connects to, in CIDR form, such as 169.254.0.0/16. Deny wins over outbound.allow.
env VLATTE_OUTBOUND_DENY, file key outbound.deny
gRPC settings:
--config string
Config file to read, in place of .vlatterc: the HTTP server's, whose grpc section this is.
env VLATTE_CONFIG, file key config
--grpc
Serve gRPC mocks: the vlatte command serves them when the grpc section is on.
env VLATTE_GRPC, file key grpc
--grpc-name string
Name of the gRPC server, in its log lines.
env VLATTE_GRPC_NAME, file key grpc.name
--grpc-addr string
Address the gRPC server listens on: host:port or :port. Default: 127.0.0.1:0.
env VLATTE_GRPC_ADDR, file key grpc.addr
--grpc-root-dir string
Directory relative mock_files patterns start at. Empty is the working directory.
env VLATTE_GRPC_ROOT_DIR, file key grpc.root_dir
--grpc-mock-files list
Glob patterns of gRPC mock files, loaded at start.
env VLATTE_GRPC_MOCK_FILES, file key grpc.mock_files
--grpc-descriptors list
Descriptor set files of the services to mock, such as protoc --descriptor_set_out --include_imports writes.
env VLATTE_GRPC_DESCRIPTORS, file key grpc.descriptors
--grpc-reflection
Serve gRPC server reflection, so grpcurl and other tools list the services.
env VLATTE_GRPC_REFLECTION, file key grpc.reflection
--grpc-template-env list
Environment variables templates may read with env, by exact name. Templates read none without it.
env VLATTE_GRPC_TEMPLATE_ENV, file key grpc.template.env
--grpc-template-keys list
Keys templates sign tokens with, jwt, and publish, jwks: kid=ALG generates one at start, such as google-1=RS256, and kid=ALG:path reads a PEM private key, relative paths starting at grpc.root_dir.
env VLATTE_GRPC_TEMPLATE_KEYS, file key grpc.template.keys
--grpc-outbound-allow list
Address ranges the gRPC server may connect to, in CIDR form, such as 10.1.0.0/16: proxied calls, the recording target and webhooks reach no other address. Empty allows every address.
env VLATTE_GRPC_OUTBOUND_ALLOW, file key grpc.outbound.allow
--grpc-outbound-deny list
Address ranges the gRPC server never connects to, in CIDR form, such as 169.254.0.0/16. Deny wins over grpc.outbound.allow.
env VLATTE_GRPC_OUTBOUND_DENY, file key grpc.outbound.deny
--grpc-tls
Serve TLS. Only the vlatte command reads it: in Go, Server.StartTLS serves TLS.
env VLATTE_GRPC_TLS, file key grpc.tls
--grpc-tls-cert string
TLS certificate file. Requires grpc.tls.key. Without one, TLS serves a self-signed certificate.
env VLATTE_GRPC_TLS_CERT, file key grpc.tls.cert
--grpc-tls-key string
TLS private key file. Requires grpc.tls.cert.
env VLATTE_GRPC_TLS_KEY, file key grpc.tls.key
--grpc-tls-ca string
File of the CA certificates that client certificates must be signed by (mutual TLS). Requires grpc.tls.cert and grpc.tls.key.
env VLATTE_GRPC_TLS_CA, file key grpc.tls.ca
--grpc-no-match-code string
Code of the answer to a call no mock matched: its name, such as UNIMPLEMENTED, or its number. Default: NOT_FOUND.
env VLATTE_GRPC_NO_MATCH_CODE, file key grpc.no_match_code
--grpc-debug-headers
Add the debug header metadata, such as vlatte-matched-mock-id, to the server's answers. Default: true.
env VLATTE_GRPC_DEBUG_HEADERS, file key grpc.debug_headers
--grpc-near-misses
Journal the mocks closest to a call no mock matched. Default: true.
env VLATTE_GRPC_NEAR_MISSES, file key grpc.near_misses
--grpc-shutdown-timeout duration
How long the server waits for the calls in flight when it stops: milliseconds or a Go duration (1.5s). Default: 5s.
env VLATTE_GRPC_SHUTDOWN_TIMEOUT, file key grpc.shutdown_timeout
--grpc-log-level name
Level of the gRPC server's log. One of: trace, debug, info, warn, error, fatal, panic, none, disabled. Default: info.
env VLATTE_GRPC_LOG_LEVEL, file key grpc.log.level
--grpc-journal
Keep a journal of the calls the gRPC server serves, of every outcome.
env VLATTE_GRPC_JOURNAL, file key grpc.journal
--grpc-journal-dir string
Directory of the journal's files, kept across restarts. Empty keeps them in a temporary directory, removed when the server stops.
env VLATTE_GRPC_JOURNAL_DIR, file key grpc.journal.dir
--grpc-journal-max-entries int
How many calls the journal keeps, the newest. 0 keeps them all. Default: 10000.
env VLATTE_GRPC_JOURNAL_MAX_ENTRIES, file key grpc.journal.max_entries
--grpc-journal-max-body-size int
How many bytes of a call's request, as JSON, the journal keeps. 0 keeps whole requests. Default: 1048576.
env VLATTE_GRPC_JOURNAL_MAX_BODY_SIZE, file key grpc.journal.max_body_size
--grpc-record
Record the calls the gRPC server proxies as mock files, from start to close.
env VLATTE_GRPC_RECORD, file key grpc.record
--grpc-record-dir string
Directory of the gRPC recordings. Relative paths start at grpc.root_dir. Default: _mocks_recorded.
env VLATTE_GRPC_RECORD_DIR, file key grpc.record.dir
--grpc-record-format string
Format of the recorded gRPC mock files: json, yaml, yml. Default: json.
env VLATTE_GRPC_RECORD_FORMAT, file key grpc.record.format
--grpc-record-target string
gRPC server to record, such as localhost:50051: the calls the recording takes go to it, without TLS, before any mock.
env VLATTE_GRPC_RECORD_TARGET, file key grpc.record.target
--grpc-record-methods list
Methods of the calls the recording takes, by whole segments of their full method, such as Service/Method. Empty takes every method.
env VLATTE_GRPC_RECORD_METHODS, file key grpc.record.methods
--grpc-record-request-headers list
Metadata keys recordings match: the value each had, or its absence.
env VLATTE_GRPC_RECORD_REQUEST_HEADERS, file key grpc.record.request_headers
--grpc-record-repeats name
What a recording keeps of a request that comes again: every answer, in order, or the first one. One of: sequence, first. Default: sequence.
env VLATTE_GRPC_RECORD_REPEATS, file key grpc.record.repeats
--grpc-record-include-mocked
Record the answers of mocks too, not only proxied ones.
env VLATTE_GRPC_RECORD_INCLUDE_MOCKED, file key grpc.record.include_mocked