cli.md

CLI Reference

The haystack CLI binary provides commands for serving, importing, exporting, validating data, and querying remote servers.

cargo build --locked -p rusty-haystack-cli --release
./target/release/haystack --help

Commands

serve

Start the Haystack HTTP API server. The Listening on banner reports the actual bound address after application readiness, including when --port 0 is used. Ctrl-C and, on Unix, SIGTERM seal admission and initiate shutdown. The CLI waits for owned HTTP/WebSocket work and provider cleanup before dropping its Tokio runtime outside the asynchronous context. If the close deadline expires, it reports the error and keeps waiting for actual termination; non-cooperative code can therefore delay process exit. See application lifecycle.

haystack serve [OPTIONS]

Flag	Short	Description	Default
--port	-p	Port to listen on	8080
--host		Host to bind to	127.0.0.1
--file	-f	Load entities from file at startup
--users	-u	TOML file with user credentials for SCRAM auth
--postgres-config		Explicit PostgreSQL TOML; requires the postgres build feature and nonempty --users; conflicts with --file/--demo	Memory
--demo		Load a demo building automation dataset
--cors-origin		Allow cross-origin browser requests from this origin (repeatable)	No CORS headers

HAYSTACK_PASSWORD supplies passwords to user and client commands. Serving reads hashed credentials from --users, not that variable. For a runnable authenticated durable server, configuration, write/history flow, restart and cleanup recipe, see standalone PostgreSQL.

Origins are matched verbatim, scheme and port included. See Configuration for what the policy allows.

Examples:

# Demo server
haystack serve --demo

# Memory server with auth
haystack serve --file data/entities.zinc --users users.toml --port 9090

# Bind to all interfaces (e.g., for Docker)
haystack serve --demo --host 0.0.0.0 --port 8080

# Reachable from a dashboard on another origin
haystack serve --demo --cors-origin https://ops.example.com

import

Import entities from a file and print summary.

haystack import <FILE> [OPTIONS]

Flag	Short	Description	Default
--format	-f	Input format: zinc, trio, json, json3	Auto-detect from extension

Examples:

haystack import data/entities.zinc
haystack import data/entities.json --format json

export

Export entities to a specified format. Reads from stdin.

haystack export [OPTIONS]

Flag	Short	Description	Default
--format	-f	Output format: zinc, trio, json, json3	zinc
--output	-o	Output file path (stdout if omitted)
--filter		Filter expression to select entities

Examples:

cat data/entities.zinc | haystack export --format json
cat data/entities.zinc | haystack export --format trio --output out.trio
cat data/entities.zinc | haystack export --filter "site" --format json

validate

Validate entities against the standard Haystack ontology.

haystack validate <FILE> [OPTIONS]

Flag	Short	Description	Default
--format	-f	Input format	Auto-detect from extension

Examples:

haystack validate data/entities.zinc
haystack validate data/entities.json --format json

info

Show information about the Haystack standard library.

haystack info [OPTIONS]

Flag	Short	Description	Default
--def	-d	Show info about a specific def	Show general stats

Examples:

haystack info
haystack info --def ahu
haystack info --def site

libs

List loaded libraries in the standard namespace.

haystack libs

Output: table of library name, version, and number of defs.

specs

List loaded Xeto specs.

haystack specs [OPTIONS]

Flag	Short	Description	Default
--lib	-l	Filter specs by library name	Show all

Examples:

haystack specs
haystack specs --lib ph

client

Query a remote Haystack server. All subcommands require --url, -U (username), and -P (password).

Common flags for all client subcommands:

Flag	Short	Description	Default
--url		Server API URL (e.g., http://localhost:8080/api)	Required
--username	-U	Username	Required
--password	-P	Password	Required
--format	-f	Output format: zinc, json, trio, json3	zinc

client about

Get server information.

haystack client about --url http://localhost:8080/api -U admin -P s3cret

client read

Read entities by filter.

haystack client read <FILTER> [OPTIONS]

Flag	Short	Description	Default
--limit	-l	Maximum rows to return	No limit

haystack client read "site" --url http://localhost:8080/api -U admin -P s3cret
haystack client read "point and temp" --limit 10 --url http://localhost:8080/api -U admin -P s3cret

client nav

Navigate the entity tree.

haystack client nav [OPTIONS]

Flag	Short	Description	Default
--nav_id		Navigation ID (omit for root)	Root

haystack client nav --url http://localhost:8080/api -U admin -P s3cret
haystack client nav --nav_id @site-1 --url http://localhost:8080/api -U admin -P s3cret

client hisread

Read historical data for a point.

haystack client hisread <ID> [OPTIONS]

Flag	Short	Description	Default
--range	-r	Date range	Required

haystack client hisread @point-1 --range today --url http://localhost:8080/api -U admin -P s3cret
haystack client hisread @point-1 --range "2024-01-01,2024-01-31" --url http://localhost:8080/api -U admin -P s3cret

client ops

List supported server operations.

haystack client ops --url http://localhost:8080/api -U admin -P s3cret

client libs

List libraries from a remote server.

haystack client libs --url http://localhost:8080/api -U admin -P s3cret

client specs

List specs from a remote server.

haystack client specs [OPTIONS]

Flag	Short	Description	Default
--lib	-l	Filter by library name	Show all

haystack client specs --url http://localhost:8080/api -U admin -P s3cret
haystack client specs --lib ph --url http://localhost:8080/api -U admin -P s3cret

user

Manage users in a TOML credentials file.

user add

Add a new user.

haystack user add <USERNAME> [OPTIONS]

Flag	Short	Description	Default
--file	-f	Path to users TOML file	Required
--password	-p	Password	Required
--permissions	-r	Comma-delimited permissions	read

haystack user add admin --file users.toml --password s3cret --permissions read,write,admin
haystack user add viewer --file users.toml --password viewpass

user delete

Delete a user.

haystack user delete <USERNAME> --file users.toml

user list

List all users and their permissions.

haystack user list --file users.toml

user passwd

Update a user's password.

haystack user passwd <USERNAME> --file users.toml --password newpass

Format Auto-Detection

When --format is omitted, the CLI detects format from the file extension:

Extension	Format
.zinc	text/zinc
.trio	text/trio
.json	application/json

For explicit control, use the --format flag with: zinc, trio, json, json3.