Finch Docs
Toggle Dark/Light/Auto modeToggle Dark/Light/Auto modeToggle Dark/Light/Auto modeBack to homepage

Command Line

  finch [options] STAGE_FILE [STAGE_FILE...]

  --client ADDR[:PORT]  Run as client of server at ADDR
  --cpu-profile FILE    Save CPU profile of stage execution to FILE
  --database (-D) DB    Default database on connect
  --debug               Print debug output to stderr
  --dsn DSN             MySQL DSN (overrides stage files)
  --help                Print help and exit
  --param (-p) KEY=VAL  Set param key=value (override stage files)
  --server ADDR[:PORT]  Run as server on ADDR
  --test                Validate stages, test connections, and exit
  --version             Print version and exit

finch 1.0.0

You must specify at least one stage file on the command line.

Finch executes stages files in the order given.

Command Line Options


Run as client connected to address and (optional) port.

Env VarValueDefaultValid Value
FINCH_CLIENTADDR[:PORT]Server address[:port]


Save CPU profile of stage execution.

Env VarValueDefaultValid Value

For example, --cpu-profile then run go tool pprof -http 127.1:8080 ./finch


Env VarValueDefaultValid Value
FINCH_DBDBDatabase name

Sets default database on connect. Does not override --dsn.


Print debug output to stderr.

Env Var

Use with --test to debug startup validation, data generators, etc.


Data source name (DSN) for all MySQL connections.

Env VarValueDefaultValid Value
FINCH_DSNDSNData Source Name

This overrides any mysql settings.

There’s no default DSN, but there is a default MySQL user.


Print help (the usage output above) and exit zero.


Set params that override all stage files.

This option can be specified multiple times:

finch --params key1=value1 --params key2=val2


Run as server on addr:port to listen on for clients.

Env VarValueDefaultValid Value
FINCH_SERVERADDR[:PORT]Interface address and port

Using value “0” or “” will bind to all interfaces on port 33075.


Start up and validate everything possible, but don’t execute any stages.

Env Var

Use with --debug to debug file syntax, workload allocation, and so forth. Finch start up is two-phase: prepare and run. This option makes Finch exit after prepare. Finch prepares everything in the prepare phase, so a successful test means that the Finch configuration is valid. The only thing Finch does not check during prepare is that the SQL statements are valid. That happens in the run phase when Finch executes the SQL statements. For example, Finch doesn’t check if “SELECT c FRM t WHRE id=1” is valid; it relies on MySQL to parse and validate SQL statements. However, statements with the prepare SQL modifier are prepared on MySQL during the Finch prepare phase, so invalid prepared SQL statements will cause an error during a Finch startup test.


Print Finch version and exit zero.