Command line
Program · Workflow Tests · Starter scripts
This page lists the commands you run with IdentityFlow 0.3.1: the IdentityFlow program, the Workflow Test distribution and the npm scripts of the starter. Install and run IdentityFlow walks through a production start step by step.
The program is one executable file named after its version and platform, for
example identity-flow-v0.3.1-linux-x64 or identity-flow-v0.3.1-macos-arm64.
/opt/identity-flow/identity-flow-v0.3.1-linux-x64 --version/opt/identity-flow/identity-flow-v0.3.1-linux-x64 --version --json--version prints one line:
IdentityFlow 0.3.1 (identity-flow/0.3.1; <source commit>; <platform>-<arch>).
--version --json prints the same facts as one JSON object, including
version, releaseId, sourceCommit, platform and arch. Neither reads
the configuration or connects to the database, so both work on a machine that
is not set up yet.
Run the program without arguments to start IdentityFlow. It reads these environment variables:
| Variable | Meaning |
|---|---|
NODE_ENV | The mode; the program defaults to production. It selects mode-specific configuration files such as identity-flow.production.conf. |
NODE_CONFIG_FILE | Path of the configuration file. |
NODE_CONFIG_DIR | Directory searched when no configuration file was found before it; see How the program finds the file. Default: ./config. |
HOST | Address to listen on. Default: 0.0.0.0. |
PORT | Port to listen on. Default: 3000. |
ORIGIN | The public address browsers use, such as https://flow.example.com. |
PG* | PostgreSQL connection settings, such as PGHOST, for values the configuration file does not set. |
The configuration file can read further variables with ${NAME}, which is how
secrets reach it; see Configuration.
The program writes its log to standard output and standard error. It is ready when
Listening on http://<host>:<port> appears. SIGINT or SIGTERM stops it.
The Workflow Test distribution runs your Workflow Tests, the *.case.ts files.
It is delivered with the release as a folder named after its version and
platform, for example identity-flow-test-v0.3.1-linux-x64. Keep the files in
the folder together; the identity-flow-test executable in it does not start
without them. Test workflows explains how to write
the tests and the vitest.config.ts they need.
Run it in your project directory, the one that contains vitest.config.ts:
/opt/identity-flow/identity-flow-test-v0.3.1-linux-x64/identity-flow-test --run--runruns every test once and exits. The exit code is0when all tests pass.- Docker must be running. Each run starts a
postgres:18.6-alpinecontainer for the tests and removes it afterwards. --helpruns nothing. It printsIdentityFlow Test does not support the Vitest help flag; no tests were executed.--versionprintsIdentityFlow Test 0.3.1 (identity-flow-test/0.3.1; <source commit>; <platform>-<arch>);--version --jsonprints the same fields as the program’s.--versionmust come first.
The distribution needs no environment variables. One is optional:
| Variable | Meaning |
|---|---|
IDENTITY_FLOW_TEST_POSTGRES_IMAGE | Container image for the test database, instead of postgres:18.6-alpine. Use a PostgreSQL 17 or 18 image. |
Plain vitest run does not run Workflow Tests. It prints
No test files found, then
The Workflow Test runtime is not included in the public @identity-flow/testing package.,
and exits with code 1. Plain Vitest runs your other tests, such as hook tests
with createHookTestHost(), but not Workflow Tests.
The starter is the example project delivered with IdentityFlow.
Run its scripts from the project directory with npm run <script>; pass
options after --, as in npm run workshop:stop -- --volumes.
| Script | What it does |
|---|---|
check | Type-checks the project with tsc --noEmit. |
check:exercises | Type-checks the practice tasks in exercises/. |
test:workflow | Runs the Workflow Tests with the distribution in bin/. Stops with IFLOW_DISTRIBUTION_MISSING or IFLOW_DISTRIBUTION_VERSION_MISMATCH when it is absent or another version. |
exercise | Type-checks and tests one practice task: npm run exercise -- 03, or its solution with -- 03 --solution. |
workshop:verify | Checks the exact versions of Node, the program, the distribution and the packages, then that the local services run. It checks this machine, not the integrity of the delivered files. |
workshop:start | Starts the local fixture services, such as PostgreSQL and the sign-in server, and the program. -- --background returns once the program is ready. |
workshop:status | Shows the running program’s PID, version, URL and log file. Exits 0 only while it runs. |
workshop:logs | Prints this run’s log. -- --follow keeps following it. |
workshop:refresh | Switches the example identity data to the coverage scenario and sends a change event. -- --scenario standard switches back. |
workshop:stop | Stops the program and the services and keeps the database. -- --volumes deletes the database too. |
workshop:inventory | Lists the Workflow Definitions the running program has deployed. |
The scripts look for the program and the distribution in bin/. Set
IDENTITY_FLOW_PROGRAM or IDENTITY_FLOW_TEST to the path of the program or
the distribution folder to use one from somewhere else. The starter’s README.md
explains the common IFLOW_* codes the scripts print.
Record these for every run you report:
- where it ran: machine, operating system, and whether it was the starter or your own project;
- the revision of your project and the package versions from its lockfile;
- the output of
--version --jsonfor the program and the distribution; - the PostgreSQL version or container image;
- the command, its exit code and its output, including any
IFLOW_*orWF_*code; - for a GraphQL error, its
extensions.codeand the program’s log lines from the same moment.
Remove credentials, tokens, full provider payloads and personal data before you save or send any of it.