wdx project

Manage projects.

Manage projects

Command	What it does
`wdx project close`	Close a project
`wdx project create`	Create a project in a new git repository
`wdx project get`	Show a project, which of its checkouts are on disk and its terminals
`wdx project landing`	Show or say how a project lands its worktrees
`wdx project list`	List projects
`wdx project open`	Open a project: a known one, a local repository or a clone
`wdx project remove`	Delete a project and everything that belongs to it
`wdx project sync`	Show, start or stop pushing a project’s docs to the hub

wdx project close

Close a project.

wdx project close (--id <id> | --name <name>) [--stop-running | --cancel] [flags]

Nothing on disk is touched; open it again with wdx project open.

Its terminals stop, and start with fresh shells when it is opened again. If any is running, you are asked first, since that ends the programs in them; --stop-running and --cancel answer in advance, and with --json one of them is required.

Flags

Flag	Default	Description
`--cancel`		if a terminal or agent is running, change nothing without asking
`--id <id>`		id of the project
`--name <name>`		name of the project (case-insensitive)
`--stop-running`		if a terminal or agent is running, stop it without asking
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --stop-running or --cancel
with --json: one of --stop-running or --cancel

Examples

# Close a project
wdx project close --name app

# From a script: stop its running terminals
wdx project close --name app --stop-running --json

Output

The closed project, with the terminals it stopped under “stopped”. With --json: {“result”: “closed”, “project”: {…}, “stopped”: […]}

With --json, result is one of: closed.

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`project_in_use`	1	terminals or agents are running in the project
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

With --node, also: code_not_set_up, code_wrong, connection_lost, daemon_unavailable, hub_unreachable, hub_version_unsupported, node_key_mismatch, node_not_found, node_offline, node_version_unsupported, not_logged_in, remote_access_off, remote_not_for_agents, route_not_allowed, session_closed, session_required, too_many_streams.

wdx project create

Create a project in a new git repository.

wdx project create --name <name> [--path <dir>] [flags]

Create an empty git repository at <dir>/<name> and open it as a project. <dir> defaults to /home/you/.wdx/projects. An existing directory that is not in a git repository is initialized in place.

If the name is taken or the directory is in a git repository, you are asked to open that project, try another name or cancel; --open and --cancel answer in advance, and with --json one of them is required. Every failure starts with “not created:”.

Flags

Flag	Default	Description
`--cancel`		on a conflict, create nothing without asking
`--name <name>`		name of the project, also the repository directory name
`--open`		on a conflict, open the existing project without asking
`--path <dir>`		parent dir of the repository (default /home/you/.wdx/projects)
`--node <name>`		run the command on the node of this name, another of your account, through a session

--name is required
at most one of --open or --cancel
with --json: one of --open or --cancel

Examples

# Create a project in ~/.wdx/projects/app
wdx project create --name app

# Create it in another directory
wdx project create --name app --path ~/src

# From a script: open the existing project if the name is taken
wdx project create --name app --open --json

Output

The created project. On a conflict answered with --open, the project opened instead, with the conflict under “conflict”. With --json: {“result”: …, “project”: {…}, “conflict”: {…}}

With --json, result is one of: cloned, created, opened, registered or removed.

Errors

Code	Exit	When
`checkout_missing`	1	none of the project’s checkouts is left on disk
`clone_failed`	1	git clone failed
`daemon_unavailable`	3	the daemon is not running or not answering
`dependency_missing`	3	a program the request needs is not installed: wdx deps list tells which
`invalid_name`	1	the name is not allowed
`invalid_path`	1	the path cannot be used
`name_taken`	1	something else has this name
`project_in_use`	1	terminals or agents are running in the project
`repo_exists`	1	the directory is already in a git repository
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx project get

Show a project, which of its checkouts are on disk and its terminals.

wdx project get (--id <id> | --name <name>) [flags]

Open and closed projects alike, with each worktree and whether it is still on disk, and every terminal in any state. A project with no checkout left on disk is orphaned. Nothing is changed.

Flags

Flag	Default	Description
`--id <id>`		id of the project
`--name <name>`		name of the project (case-insensitive)
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name

Examples

# Show a project by name
wdx project get --name app

# By id, as JSON
wdx project get --id proj-1a2b3c4d --json

Output

The project with its worktrees, “present” telling whether each is on disk, “orphaned” that none is, and “terminals” by name. With --json: {“project”: {…}}

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`dependency_missing`	3	a program the request needs is not installed: wdx deps list tells which
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx project landing

Show or say how a project lands its worktrees.

wdx project landing (--id <id> | --name <name>) [--check <command> | --no-check] [--push] [--method <method>] [flags]

With --check or --no-check, saves it: the command wdx worktree land runs before moving the base, and with --push whether it then pushes the base to origin. With --method pr too, it opens a PR with gh rather than moving the base. Without them, it shows what is saved. Landing needs it to have been said once.

Flags

Flag	Default	Description
`--check <command>`		command to run before landing
`--id <id>`		id of the project
`--method <method>`		method of landing, rebase or pr; what is saved when not given
`--name <name>`		name of the project (case-insensitive)
`--no-check`		run nothing before landing
`--push`		push the base to origin once it moved
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --check or --no-check

Examples

# Show how a project lands
wdx project landing --name app

# Check before landing
wdx project landing --name app --check make-test

# No check, and push
wdx project landing --name app --no-check --push --json

# Land through PRs
wdx project landing --name app --no-check --method pr

Output

How the project lands. With --json: {“configured”: true, “method”: “rebase”, “check”: “…”, “push”: false}

With --json, result is one of: updated.

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx project list

List projects.

wdx project list [--all | --open | --closed] [flags]

Projects are listed without their worktrees. With no flag, every project is listed.

Flags

Flag	Default	Description
`--all`		list every project (the default)
`--closed`		list only closed projects
`--open`		list only open projects
`--node <name>`		run the command on the node of this name, another of your account, through a session

at most one of --all, --open or --closed

Examples

# Every project
wdx project list

# Only the open ones, as JSON
wdx project list --open --json

Output

The projects sorted by name, each with its number of worktrees; an empty list when none match. With --json: {“projects”: […]}

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx project open

Open a project: a known one, a local repository or a clone.

wdx project open [--local <path> | --git <url> | --id <id> | --name <name>] [flags]

With no flags on a terminal, you choose from a list: create a project, open a local repository, clone one, or any closed project. Without a terminal, or with --json, a flag is required.

--id or --name alone opens a known project. It is marked open again, its checkouts no longer on disk are dropped, and the terminals and agents closing it stopped start again.

--local opens the repository a path is in, at its root. Worktrees and other clones of a known repository join its project.

--git opens the project with that origin, or clones it into /home/you/.wdx/projects/<name> if it is unknown.

If none of a known project’s checkouts are left, you are asked to clone it again or remove it; --reclone and --remove answer in advance, and with --json one of them is required, except with --local.

With --local or --git, --name names the project, by default after its root directory or URL. Names are unique.

Flags

Flag	Default	Description
`--git <url>`		url of a git repository to clone
`--id <id>`		id of a known project
`--local <path>`		path to a local git repository
`--name <name>`		name of a known project; with `--local` or `--git`, the name to give it (default: the repository directory or URL name)
`--reclone`		if no checkout is left, clone it again without asking
`--remove`		if no checkout is left, remove the project without asking
`--node <name>`		run the command on the node of this name, another of your account, through a session

at most one of --local, --git or --id
at most one of --id or --name
at most one of --local or --reclone
at most one of --local or --remove
at most one of --reclone or --remove
with --json and --git: one of --reclone or --remove
with --json and --id: one of --reclone or --remove
with --json and --name, unless --local: one of --reclone or --remove

Examples

# Open the repository you are in
wdx project open --local .

# Choose from a list
wdx project open

# Open a closed project by name
wdx project open --name app

# Clone a repository and open it under another name
wdx project open --git https://github.com/acme/api.git --name acme-api

# From a script: clone again if no checkout is left, never prompt
wdx project open --id proj-1a2b3c4d --reclone --json

Output

The project, with the checkouts dropped because they are no longer on disk under “dropped”, and the terminals closing it stopped, started again, under “started”. With --json: {“result”: …, “project”: {…}, “dropped”: […], “started”: […]}

With --json, result is one of: cloned, created, opened, registered or removed.

Errors

Code	Exit	When
`cancelled`	1	the question was answered no
`checkout_missing`	1	none of the project’s checkouts is left on disk
`clone_failed`	1	git clone failed
`daemon_unavailable`	3	the daemon is not running or not answering
`dependency_missing`	3	a program the request needs is not installed: wdx deps list tells which
`invalid_argument`	1	an argument is empty or malformed
`invalid_name`	1	the name is not allowed
`invalid_path`	1	the path cannot be used
`name_taken`	1	something else has this name
`not_found`	1	nothing has this name or id
`not_git_repo`	1	the path is not in a git repository
`path_exists`	1	something is already at the path, as the directory to clone into
`project_in_use`	1	terminals or agents are running in the project
`project_mismatch`	1	the repository is a worktree of one project but has the origin of another
`repo_exists`	1	the directory is already in a git repository
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx project remove

Delete a project and everything that belongs to it.

wdx project remove (--id <id> | --name <name>) [--stop-running | --cancel] [flags]

It is removed from wdx only: files on disk are not touched.

Its terminals are removed too. If any is running, you are asked first, since stopping it ends the programs in it; --stop-running and --cancel answer in advance, and with --json one of them is required.

Flags

Flag	Default	Description
`--cancel`		if a terminal or agent is running, change nothing without asking
`--id <id>`		id of the project
`--name <name>`		name of the project (case-insensitive)
`--stop-running`		if a terminal or agent is running, stop it without asking
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --stop-running or --cancel
with --json: one of --stop-running or --cancel

Examples

# Remove a project
wdx project remove --name app

# By id, as JSON, stopping its running terminals
wdx project remove --id proj-1a2b3c4d --stop-running --json

Output

The removed project, with the terminals it stopped under “stopped”. With --json: {“result”: “removed”, “project”: {…}, “stopped”: […]}

With --json, result is one of: removed.

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`not_found`	1	nothing has this name or id
`project_in_use`	1	terminals or agents are running in the project
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx project sync

Show, start or stop pushing a project’s docs to the hub.

wdx project sync (--id <id> | --name <name>) [--on | --off] [flags]

With --on, every doc of the project goes up to the hub with all its revisions, then each change as it happens; plans never do. With --off, it stops, and what is on the hub stays there. Both work logged out or offline: changes wait for the connection. Without either, it shows what is waiting and what the hub refused. The project needs a git remote, whose key the hub files its docs under.

Flags

Flag	Default	Description
`--id <id>`		id of the project
`--name <name>`		name of the project (case-insensitive)
`--off`		stop pushing them
`--on`		push the project’s docs to the hub
`--node <name>`		run the command on the node of this name, another of your account, through a session

exactly one of --id or --name
at most one of --on or --off

Examples

# Show how far a project's docs are on the hub
wdx project sync --name app

# Push its docs
wdx project sync --name app --on

# Stop, as JSON
wdx project sync --id proj-1a2b3c4d --off --json

Output

Whether it is on, the changes waiting, each doc the hub refused with its code, when a change last reached the hub and the repository key. With --json: {“sync”: {“on”: true, “pending”: 3, “failed”: […], “last_pushed_at”: “…”, “repo_key”: “…”, “logged_in”: true}}, with “result” too given --on or --off

With --json, result is one of: changed or unchanged.

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`no_remote`	1	the project has no git remote, whose key the hub files its docs under
`not_found`	1	nothing has this name or id
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git