CLI: project

Read the CLI overview for session/CWD resolution, exit conventions, role boundaries, synthetic IDs and execution authorization. This page documents leaf-specific exceptions; the commands are not a script to run in order.

viat project create
viat project diff
viat project folderize
viat project init
viat project list
viat project member add
viat project member ls
viat project member rm
viat project member set-role
viat project select

viat project create

Prerequisites and permissions. A configured server and platform login; no selected project required. Use the synthetic names below only in your isolated demo project; replace identifiers with values returned by its list/create commands.

Usage: viat project create <SLUG> <NAME>

Command aliases: none.

Argument ID / all spellings	Type, value count, action	Required / default	Allowed values	Conflicts, aliases, parsing and original Clap help
`help`: `--help` / `-h`	`String`, 0, `Help`	no; conditional requirements below; no explicit Clap default	—	help: Print help
`name`: `<NAME> (#2)`	`String`, 1, `Set`	yes; no explicit Clap default	—	—
`slug`: `<SLUG> (#1)`	`String`, 1, `Set`	yes; no explicit Clap default	—	—

Clap argument groups (literal metadata): {"arguments":["name","slug"],"id":"Create","multiple":true,"required":false}

Inputs, behavior and side effects. POST /projects creates a remote-only project and makes the creator Owner. Does not scaffold files or select it. Slug and display name are separate positional values.

Actual output and exit. stdout: created <slug>; 0 after successful response. Unless this section states otherwise, normal completion is 0; argument/file/HTTP/runtime errors are nonzero (typically 2 for parsing, 1 for runtime errors).

Synthetic invocation (syntax validation only; not executed).

viat project create cli-demo 'CLI Demo'

Failure handling, verification and cleanup. Duplicate/invalid slug fails without creating another project. Verify project list; select explicitly. Delete an unwanted demo project through the console/API (there is no project delete CLI leaf).

viat project diff

Prerequisites and permissions. Platform login, selected project, and membership in that project (including Operator). Use the synthetic names below only in your isolated demo project; replace identifiers with values returned by its list/create commands.

Usage: viat project diff [OPTIONS]

Command aliases: none.

Argument ID / all spellings	Type, value count, action	Required / default	Allowed values	Conflicts, aliases, parsing and original Clap help
`exit_code`: `--exit-code`	`bool`, 0, `SetTrue`	no; conditional requirements below; `false`	—	help: Exit 1 if there are any differences (matches `git diff --exit-code`)
`help`: `--help` / `-h`	`String`, 0, `Help`	no; conditional requirements below; no explicit Clap default	—	help: Print help
`json`: `--json`	`bool`, 0, `SetTrue`	no; conditional requirements below; `false`	—	—
`only`: `--only`	`String`, 1, `Append`	no; conditional requirements below; no explicit Clap default	—	value delimiter: ”,”

Clap argument groups (literal metadata): {"arguments":["exit_code","json","only"],"id":"Diff","multiple":true,"required":false}

Inputs, behavior and side effects. Compares CWD repository content to remote drafts, not publish state or a push request plan. —only validates kinds; crate is not supported. Script/workflow/resource server-only items are informational because push does not delete them.

Actual output and exit. Text marks added/removed/changed/server-only; —json gives stages with added, removed, changed and server_only arrays. —exit-code exits 1 for real differences, not informational server_only; otherwise differences still exit 0. Unless this section states otherwise, normal completion is 0; argument/file/HTTP/runtime errors are nonzero (typically 2 for parsing, 1 for runtime errors).

Synthetic invocation (syntax validation only; not executed).

viat project diff --only scripts,workflows --exit-code

Failure handling, verification and cleanup. Run from a complete repo root and select intended project. Unknown kind fails; read permissions for metadata may require editor. Resolve draft drift before push; no remote changes to undo.

viat project folderize

Prerequisites and permissions. Platform login, selected project, and effective project Owner/Admin; Developer/Operator cannot publish. Use the synthetic names below only in your isolated demo project; replace identifiers with values returned by its list/create commands.

Usage: viat project folderize [OPTIONS] --prefix <PREFIXES>

Command aliases: none.

Argument ID / all spellings	Type, value count, action	Required / default	Allowed values	Conflicts, aliases, parsing and original Clap help
`apply`: `--apply`	`bool`, 0, `SetTrue`	no; conditional requirements below; `false`	—	help: Actually apply the migration (single server-side transaction)
`help`: `--help` / `-h`	`String`, 0, `Help`	no; conditional requirements below; no explicit Clap default	—	help: Print help
`json`: `--json`	`bool`, 0, `SetTrue`	no; conditional requirements below; `false`	—	—
`prefixes`: `--prefix`	`String`, 1, `Append`	yes; no explicit Clap default	—	help: Prefix to split on (repeatable). `jzyx` moves `jzyx_util` to `jzyx/util`

Clap argument groups (literal metadata): {"arguments":["apply","json","prefixes"],"id":"Folderize","multiple":true,"required":false}

Inputs, behavior and side effects. Dry-run by default; —apply performs a server-side transactional prefix-to-folder rename with reference rewrites while preserving UUIDs. Repeated —prefix selects legacy prefixes. This requires project Owner/Admin.

Actual output and exit. Prints planned/applied moves and rewrites; —json returns plan/result. Published snapshots do not change until republish. Unless this section states otherwise, normal completion is 0; argument/file/HTTP/runtime errors are nonzero (typically 2 for parsing, 1 for runtime errors).

Synthetic invocation (syntax validation only; not executed).

viat project folderize --prefix legacy --json

Failure handling, verification and cleanup. Collisions refuse instead of overwriting. Review dry-run, then apply and pull: local old filenames are stale. There is no inverse folderize option; retain a backup and explicitly rename/rewrite to undo.

viat project init

Usage: viat project init [OPTIONS] <SLUG>

Command aliases: none.

Argument ID / all spellings	Type, value count, action	Required / default	Allowed values	Conflicts, aliases, parsing and original Clap help
`help`: `--help` / `-h`	`String`, 0, `Help`	no; conditional requirements below; no explicit Clap default	—	help: Print help
`here`: `--here`	`bool`, 0, `SetTrue`	no; conditional requirements below; `false`	—	help: Scaffold in CWD instead of ./<slug>/. CWD must be empty (apart from .git/.idea/.claude)
`name`: `--name`	`String`, 1, `Set`	no; conditional requirements below; no explicit Clap default ; runtime: `slug`	—	—
`server`: `--server`	`String`, 1, `Set`	no; conditional requirements below; no explicit Clap default ; runtime: `resolved config server_url`	—	help: Override server URL (otherwise uses the loaded config)
`slug`: `<SLUG> (#1)`	`String`, 1, `Set`	yes; no explicit Clap default	—	—

Clap argument groups (literal metadata): {"arguments":["here","name","server","slug"],"id":"Init","multiple":true,"required":false}

Inputs, behavior and side effects. Creates the remote project and a local repo (default ./<slug>, —here uses CWD). Runtime —name defaults to slug. —here permits only .git/.idea/.claude/.vscode/.viat; otherwise refuses nonempty dirs. Writes .viat/config.yaml, viat.yaml and endpoints/scripts/workflows/schedules/watches/ws_triggers/resources directories. —server overrides destination, not login authority.

Actual output and exit. Prints remote creation, scaffold path and selected project. New repo config selects the project. No push or publish occurs. Unless this section states otherwise, normal completion is 0; argument/file/HTTP/runtime errors are nonzero (typically 2 for parsing, 1 for runtime errors).

Synthetic invocation (syntax validation only; not executed).

viat project init cli-demo --name 'CLI Demo'

Failure handling, verification and cleanup. Not transactional across remote/filesystem: failures can leave a directory or created project. Inspect both before retrying; do not blindly delete a non-demo project. Remove disposable local scaffold and delete the remote demo through console/API when done.

viat project list

Usage: viat project list [OPTIONS]

Command aliases: none.

Argument ID / all spellings	Type, value count, action	Required / default	Allowed values	Conflicts, aliases, parsing and original Clap help
`help`: `--help` / `-h`	`String`, 0, `Help`	no; conditional requirements below; no explicit Clap default	—	help: Print help
`json`: `--json`	`bool`, 0, `SetTrue`	no; conditional requirements below; `false`	—	—

Clap argument groups (literal metadata): {"arguments":["json"],"id":"List","multiple":true,"required":false}

Inputs, behavior and side effects. GET /projects lists only projects the caller can access; platform rank alone does not supply project membership.

Actual output and exit. Text shows slug, display name and * on selected project; —json emits the server list. Empty list is successful. Unless this section states otherwise, normal completion is 0; argument/file/HTTP/runtime errors are nonzero (typically 2 for parsing, 1 for runtime errors).

Synthetic invocation (syntax validation only; not executed).

viat project list --json

Failure handling, verification and cleanup. Missing projects require membership, not repeated select attempts. No mutation or cleanup.

viat project member add

Usage: viat project member add [OPTIONS] --role <ROLE> <EMAIL>

Command aliases: none.

Argument ID / all spellings	Type, value count, action	Required / default	Allowed values	Conflicts, aliases, parsing and original Clap help
`email`: `<EMAIL> (#1)`	`String`, 1, `Set`	yes; no explicit Clap default	—	—
`help`: `--help` / `-h`	`String`, 0, `Help`	no; conditional requirements below; no explicit Clap default	—	help: Print help
`json`: `--json`	`bool`, 0, `SetTrue`	no; conditional requirements below; `false`	—	—
`role`: `--role`	`String`, 1, `Set`	yes; no explicit Clap default	—	help: Project role: owner\|admin\|developer\|operator

Clap argument groups (literal metadata): {"arguments":["email","json","role"],"id":"Add","multiple":true,"required":false}

Inputs, behavior and side effects. Adds an existing platform email with independent project owner/admin/developer/operator role. CLI normalizes role case. This does not invite an unregistered account.

Actual output and exit. Text: <email> added to <slug> as <role>; —json prints response. Membership is effective immediately. Unless this section states otherwise, normal completion is 0; argument/file/HTTP/runtime errors are nonzero (typically 2 for parsing, 1 for runtime errors).

Synthetic invocation (syntax validation only; not executed).

viat project member add teammate@example.invalid --role developer

Failure handling, verification and cleanup. Unknown email fails: use user invite —project with —role for a new account. Verify member ls; member rm removes demo membership, subject to last-owner guard.

viat project member ls

Usage: viat project member ls [OPTIONS]

Command aliases: none.

Argument ID / all spellings	Type, value count, action	Required / default	Allowed values	Conflicts, aliases, parsing and original Clap help
`help`: `--help` / `-h`	`String`, 0, `Help`	no; conditional requirements below; no explicit Clap default	—	help: Print help
`json`: `--json`	`bool`, 0, `SetTrue`	no; conditional requirements below; `false`	—	—

Clap argument groups (literal metadata): {"arguments":["json"],"id":"Ls","multiple":true,"required":false}

Inputs, behavior and side effects. GET selected project /members; project collaborators are platform accounts, not p-user rows.

Actual output and exit. Text: email, role, display name or (no members); —json preserves user_id and timestamps. Unless this section states otherwise, normal completion is 0; argument/file/HTTP/runtime errors are nonzero (typically 2 for parsing, 1 for runtime errors).

Synthetic invocation (syntax validation only; not executed).

viat project member ls --json

Failure handling, verification and cleanup. 403 means no membership. Obtain access from a project Owner/Admin; read-only, no cleanup.

viat project member rm

Usage: viat project member rm [OPTIONS] <EMAIL>

Command aliases: none.

Argument ID / all spellings	Type, value count, action	Required / default	Allowed values	Conflicts, aliases, parsing and original Clap help
`email`: `<EMAIL> (#1)`	`String`, 1, `Set`	yes; no explicit Clap default	—	—
`help`: `--help` / `-h`	`String`, 0, `Help`	no; conditional requirements below; no explicit Clap default	—	help: Print help
`json`: `--json`	`bool`, 0, `SetTrue`	no; conditional requirements below; `false`	—	—

Clap argument groups (literal metadata): {"arguments":["email","json"],"id":"Rm","multiple":true,"required":false}

Inputs, behavior and side effects. DELETE membership by email, including self if another Owner remains. Removes that membership’s push-device registrations; rejoining does not restore registrations. Cannot remove the last Owner.

Actual output and exit. Text: <email> removed from <slug>; —json prints {ok:true}. Project access is lost immediately. Unless this section states otherwise, normal completion is 0; argument/file/HTTP/runtime errors are nonzero (typically 2 for parsing, 1 for runtime errors).

Synthetic invocation (syntax validation only; not executed).

viat project member rm teammate@example.invalid

Failure handling, verification and cleanup. Last-owner refusal needs another Owner first. Re-add with original role to restore membership, and re-register devices separately. Platform account itself is not deleted.

viat project member set-role

Usage: viat project member set-role [OPTIONS] <EMAIL> <ROLE>

Command aliases: none.

Argument ID / all spellings	Type, value count, action	Required / default	Allowed values	Conflicts, aliases, parsing and original Clap help
`email`: `<EMAIL> (#1)`	`String`, 1, `Set`	yes; no explicit Clap default	—	—
`help`: `--help` / `-h`	`String`, 0, `Help`	no; conditional requirements below; no explicit Clap default	—	help: Print help
`json`: `--json`	`bool`, 0, `SetTrue`	no; conditional requirements below; `false`	—	—
`role`: `<ROLE> (#2)`	`String`, 1, `Set`	yes; no explicit Clap default	—	—

Clap argument groups (literal metadata): {"arguments":["email","json","role"],"id":"SetRole","multiple":true,"required":false}

Inputs, behavior and side effects. PUT member role by email. Project role is independent of platform user set-role. Cannot demote the last project Owner.

Actual output and exit. Text: <email> is now <role> in <slug>; —json prints response. Access changes immediately. Unless this section states otherwise, normal completion is 0; argument/file/HTTP/runtime errors are nonzero (typically 2 for parsing, 1 for runtime errors).

Synthetic invocation (syntax validation only; not executed).

viat project member set-role teammate@example.invalid operator

Failure handling, verification and cleanup. Promote another Owner before demotion; invalid/nonmember email fails. Record original role and restore with set-role; verify member ls.

viat project select

Usage: viat project select <SLUG>

Command aliases: none.

Argument ID / all spellings	Type, value count, action	Required / default	Allowed values	Conflicts, aliases, parsing and original Clap help
`help`: `--help` / `-h`	`String`, 0, `Help`	no; conditional requirements below; no explicit Clap default	—	help: Print help
`slug`: `<SLUG> (#1)`	`String`, 1, `Set`	yes; no explicit Clap default	—	—

Clap argument groups (literal metadata): {"arguments":["slug"],"id":"Select","multiple":true,"required":false}

Inputs, behavior and side effects. Checks slug against GET /projects, then saves current_project in the resolved local config. It does not cd, pull, scaffold, or mint a project token.

Actual output and exit. stdout: selected cli-demo; success 0. Local selection changes subsequent project-scoped commands. Unless this section states otherwise, normal completion is 0; argument/file/HTTP/runtime errors are nonzero (typically 2 for parsing, 1 for runtime errors).

Synthetic invocation (syntax validation only; not executed).

viat project select cli-demo

Failure handling, verification and cleanup. Unknown/inaccessible slug exits 1 and is not selected. Verify project list; select the previous slug to undo.

Implementation evidence

Grammar comes from the pinned Clap contract and main.rs; behavior/permissions were checked against these files. Paths are relative to the product repository root.

crates/viat-cli/src/commands/project.rs
crates/viat-cli/src/commands/diff.rs
crates/viat-cli/src/repo/diff.rs
crates/viat-api/src/handlers/projects.rs