CLI Reference

Command overview

zeptoz init <project>
zeptoz collection create <name> [fields...] --id-strategy <int|uuidv4|uuidv7|ulid|nanoid>
zeptoz collection policy set <name> [--list-policy ...] [--view-policy ...] [--create-policy ...] [--update-policy ...] [--delete-policy ...]
zeptoz relation add <collection> <name> <belongs_to|has_one|has_many|many_to_many> <target> [options]
zeptoz hook add <collection> <event> --lang <rs|js|ts>
zeptoz dev --project-root .
zeptoz deploy --project-root . --output ./dist

zeptoz init

Initialize a new Zeptoz project directory.

Generated files/DB side effects are documented in Bootstrap & Generated Artifacts.

Option / Arg	Default	Values / Format	Description
<project_name>	none	directory name	Project directory to initialize.
--dry-run	false	switch	Print planned file/DB actions without writing.

zeptoz collection create

Create a collection schema and database table.

Generated files/DB side effects are documented in Bootstrap & Generated Artifacts.

Option / Arg	Default	Values / Format	Description
<name>	none	collection name	Collection name to create.
[fields...]	empty	name:type[:modifier...]	Field definitions.
--id-strategy	int	int, uuidv4, uuidv7, ulid, nanoid	Record ID strategy for this collection.
--with-hook	none	<event>:<lang>:<name>	One-shot hook scaffold + binding during collection create.
--list-policy	none	policy expression or null	Optional list Access Policy for this collection.
--view-policy	none	policy expression or null	Optional view Access Policy for this collection.
--create-policy	none	policy expression or null	Optional create Access Policy for this collection.
--update-policy	none	policy expression or null	Optional update Access Policy for this collection.
--delete-policy	none	policy expression or null	Optional delete Access Policy for this collection.
--dry-run	false	switch	Print planned DB/filesystem actions only.

zeptoz collection policy set

Update Access Policies on an existing collection.

Generated files/DB side effects are documented in Bootstrap & Generated Artifacts.

Option / Arg	Default	Values / Format	Description
<name>	none	collection name	Collection name to update.
--list-policy	unchanged	policy expression or null	Set/clear list Access Policy.
--view-policy	unchanged	policy expression or null	Set/clear view Access Policy.
--create-policy	unchanged	policy expression or null	Set/clear create Access Policy.
--update-policy	unchanged	policy expression or null	Set/clear update Access Policy.
--delete-policy	unchanged	policy expression or null	Set/clear delete Access Policy.
--dry-run	false	switch	Print planned DB changes only.

zeptoz hook add

Register and optionally scaffold a hook for a collection event.

Generated files/DB side effects are documented in Bootstrap & Generated Artifacts.

Option / Arg	Default	Values / Format	Description
<collection>	none	collection name	Target collection name.
<event>	none	hook event string	Lifecycle event to bind (for example before_insert).
--lang	none	rs, ts, js, py	Hook language alias.
--source	none	file path	Use an existing source file.
--new	none	hook name	Scaffold a new hook source file.
--dry-run	false	switch	Print planned writes/DB inserts only.

Notes:

• --source and --new are mutually exclusive.
• For TypeScript hooks, Zeptoz writes hooks/_sdk/types.d.ts for typing support.

zeptoz relation add

Create relation metadata and supporting database structures.

Option / Arg	Default	Values / Format	Description
<collection>	none	collection name	Source collection.
<name>	none	relation name	Relation identifier used in API payload/filter/expand.
<kind>	none	belongs_to, has_one, has_many, many_to_many	Relation cardinality.
<target>	none	collection name	Target collection.
--fk-column	<name>_id	field name	FK field for belongs_to/has_one. Ignored for has_many/many_to_many.
--via	none	relation name	Required for has_one/has_many. Must point to target-side belongs_to relation name.
--through	rel_<collection>_<name>	table name	Optional for many_to_many. If omitted, Zeptoz auto-generates through table name and FK columns (<collection>_id, <target>_id).
--on-delete	restrict	restrict, cascade, set_null	Used for belongs_to/has_one when deleting referenced target records.
--on-update	restrict	restrict, cascade, set_null	Used for belongs_to/has_one reassignment checks on patch/update.
--required	false	switch	For belongs_to/has_one, relation value is required on create and FK is non-nullable.
--auto	none	auth.id / request.path.* / request.query.* / literal:*	Declarative auto-assignment source for belongs_to/has_one.
--strict	false	switch	Only with --auto: always override client-provided relation value.
--mutable-after-create	false	switch	Only with --auto: allow reassignment after create (default is immutable).
--dry-run	false	switch	Print planned DB changes only.

zeptoz dev

Run Zeptoz in development mode.

Option / Arg	Default	Values / Format	Description
--project-root	.	path	Project root containing zeptoz.toml.

zeptoz deploy

Build deployment artifacts from a project.

Option / Arg	Default	Values / Format	Description
--project-root	.	path	Project root containing zeptoz.toml.
--output	./dist	path	Output directory for artifacts.
--target	<os>-<arch>	target label	Target triple label used in artifact naming.
--manifest-only	false	switch	Write runtime manifest only, skip tarball creation.
--dry-run	false	switch	Print planned file operations only.

Examples

zeptoz collection create Task title:string:required done:bool:default=false --id-strategy uuidv7
zeptoz collection policy set task --view-policy "@record.owner_id = @request.auth.id"
zeptoz relation add task owner belongs_to users --required --auto auth.id
zeptoz relation add comment post belongs_to post --on-delete cascade
zeptoz hook add Task after_insert --lang ts --new notify