wdx hub

Make this machine a node of an account on a hub, and see the account’s nodes.

A hub keeps an account’s nodes, the machines its user logged in from. The daemon keeps a connection to it while logged in, and never waits on it: with the hub down, everything else works as before.

Command	What it does
`wdx hub audit verify`	Check that no row of the node’s audit chain was changed, removed or inserted
`wdx hub code recover`	Set up a new authenticator entry with the recovery key, when the old is lost
`wdx hub code setup`	Set up an authenticator entry for this node, and get its recovery key
`wdx hub login`	Make this machine a node of your account on a hub
`wdx hub logout`	Leave the hub: this machine is no longer a node of the account
`wdx hub node get`	Show a node of your account, with its key’s fingerprint
`wdx hub node list`	List the nodes of your account, and which are online
`wdx hub node remove`	Remove another node from your account, cutting it off at once
`wdx hub session close`	Close a session, or every one, either way
`wdx hub session list`	List the sessions open into this node and from it
`wdx hub session open`	Open a session into another node of your account, with its code
`wdx hub status`	Show this machine’s login to a hub and its connection

wdx hub audit verify

Check that no row of the node’s audit chain was changed, removed or inserted.

wdx hub audit verify [flags]

The daemon walks the chain in order, recomputing each row’s hash, and stops at the first that does not match. It works logged out.

Examples

# Verify the audit chain
wdx hub audit verify

# As JSON
wdx hub audit verify --json

Output

How many rows the chain has and the last one’s hash. With --json: {“audit”: {“rows”: …, “head”: …}}

Errors

Code	Exit	When
`audit_broken`	1	a row of the node’s audit chain does not match its hash: the chain was changed
`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 hub code recover

Set up a new authenticator entry with the recovery key, when the old is lost.

wdx hub code recover [flags]

You type the recovery key, hidden as you type it; a wrong one makes the next try wait, from 1 second doubling to 5 minutes. A right one goes on as setup does, with a new recovery key at the end: the old one is spent.

Examples

# Recover this node's code
wdx hub code recover

Output

The entry’s label and the new recovery key, once. Interactive only: no --json.

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

Errors

Code	Exit	When
`code_not_set_up`	1	no authenticator code is set up on the node
`code_wrong`	1	the code is wrong, used already, or came too soon after a wrong one
`daemon_unavailable`	3	the daemon is not running or not answering
`not_logged_in`	1	this node is not logged in to a hub, or the hub cut it off
`recovery_key_wrong`	1	the recovery key is wrong, or came too soon after a wrong one
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx hub code setup

Set up an authenticator entry for this node, and get its recovery key.

wdx hub code setup [--replace] [flags]

A QR code for your authenticator app is shown, with the secret as text for an app that cannot scan; you type a code from the app back, three tries at most, and get a recovery key, shown once. With a code set up already, --replace replaces it, asking first: the old entry stops working, and the sessions open stay. Sessions also need hub.remote_access on.

Flags

Flag	Default	Description
`--replace`		replace the code set up, asking first

Examples

# Set up this node's code
wdx hub code setup

# Replace it with a new entry
wdx hub code setup --replace

Output

The entry’s label and the recovery key, once. Interactive only: no --json.

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

Errors

Code	Exit	When
`cancelled`	1	the question was answered no
`code_exists`	1	an authenticator code is set up on this node already
`code_wrong`	1	the code is wrong, used already, or came too soon after a wrong one
`daemon_unavailable`	3	the daemon is not running or not answering
`not_logged_in`	1	this node is not logged in to a hub, or the hub cut it off
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

Make this machine a node of your account on a hub.

wdx hub login --url <url> [--name <name>] [--no-browser] [flags]

--url names the hub: a wdx-hub you or your organisation run. There is no default hub.

The browser opens on the hub’s page, where you log in and approve the machine; the link is printed too, for when none opens. With --no-browser, or without a browser to open (wdx deps list), the hub’s page and a code to type on it are printed instead, to open in a browser on any device. What to open, and the code, go to stderr, with --json too. The login waits until it is approved or denied, at most 10 minutes; Ctrl-C cancels it.

The url is https, or plain http to localhost or 127.0.0.1 only.

Flags

Flag	Default	Description
`--name <name>`		name of this node in the account; the hostname by default
`--no-browser`		open no browser: print the hub’s page and a code to type on it
`--url <url>`		url of the hub to log in to, as https://hub.example.com

--url is required

Examples

# Log in to your hub, in the browser
wdx hub login --url https://hub.example.com

# Over SSH, with a code typed on another device
wdx hub login --url https://hub.example.com --no-browser

# Name the node, from a script
wdx hub login --url https://hub.example.com --name laptop --no-browser --json

Output

The hub’s status once logged in. With --json: {“result”: “logged_in”, “hub”: {…}}; the link and code still go to stderr

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

Errors

Code	Exit	When
`already_logged_in`	1	this node is logged in to a hub already
`daemon_unavailable`	3	the daemon is not running or not answering
`hub_unreachable`	3	the hub cannot be reached, or did not answer as a hub does
`hub_version_unsupported`	1	the hub serves no version of the API this wdx speaks
`invalid_argument`	1	an argument is empty or malformed
`login_cancelled`	1	the login was cancelled, or another replaced it
`login_denied`	1	the login was denied on the hub, or the account is disabled
`login_expired`	1	the login was not approved in time
`name_taken`	1	something else has this name
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx hub logout

Leave the hub: this machine is no longer a node of the account.

wdx hub logout [flags]

The hub is asked to revoke this node, then the node’s key, certificate and login are deleted here, whether the hub heard or not: without its key, the node is of no use to anyone. Projects, agents and docs stay.

Examples

# Leave the hub
wdx hub logout

# From a script
wdx hub logout --json

Output

That it left, and whether the hub heard. With --json: {“result”: “logged_out”, “hub_told”: true|false, “hub”: {…}}, the hub as it was

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

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`not_logged_in`	1	this node is not logged in to a hub, or the hub cut it off
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx hub node get

Show a node of your account, with its key’s fingerprint.

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

Show a node of your account, with its key’s fingerprint

Flags

Flag	Default	Description
`--id <id>`		id of the node
`--name <name>`		name of the node (case-insensitive)

exactly one of --id or --name

Examples

# A node by name
wdx hub node get --name laptop

# By id, as JSON
wdx hub node get --id node-1a2b3c4d --json

Output

The node. With --json: {“node”: {…}}

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`hub_unreachable`	3	the hub cannot be reached, or did not answer as a hub does
`hub_version_unsupported`	1	the hub serves no version of the API this wdx speaks
`node_not_found`	1	the account has no node of this name or id
`not_logged_in`	1	this node is not logged in to a hub, or the hub cut it off
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx hub node list

List the nodes of your account, and which are online.

wdx hub node list [flags]

List the nodes of your account, and which are online

Examples

# Every node of the account
wdx hub node list

# As JSON
wdx hub node list --json

Output

The nodes by name, this one marked. With --json: {“nodes”: […]}

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`hub_unreachable`	3	the hub cannot be reached, or did not answer as a hub does
`hub_version_unsupported`	1	the hub serves no version of the API this wdx speaks
`not_logged_in`	1	this node is not logged in to a hub, or the hub cut it off
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx hub node remove

Remove another node from your account, cutting it off at once.

wdx hub node remove (--id <id> | --name <name>) [--yes] [flags]

The hub closes its connection and renews no certificate for it. You are asked first; --yes answers in advance, and with --json, or without a terminal, it is required. This machine cannot remove itself: wdx hub logout does.

Flags

Flag	Default	Description
`--id <id>`		id of the node
`--name <name>`		name of the node (case-insensitive)
`--yes`		remove it without asking

exactly one of --id or --name
with --json: one of --yes

Examples

# Remove a lost laptop
wdx hub node remove --name laptop

# From a script
wdx hub node remove --id node-1a2b3c4d --yes --json

Output

The removed node, as it was. With --json: {“result”: “removed”, “node”: {…}}

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

Errors

Code	Exit	When
`cancelled`	1	the question was answered no
`daemon_unavailable`	3	the daemon is not running or not answering
`hub_unreachable`	3	the hub cannot be reached, or did not answer as a hub does
`hub_version_unsupported`	1	the hub serves no version of the API this wdx speaks
`node_is_this`	1	the node is this one: leaving is wdx hub logout
`node_not_found`	1	the account has no node of this name or id
`not_logged_in`	1	this node is not logged in to a hub, or the hub cut it off
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx hub session close

Close a session, or every one, either way.

wdx hub session close (--id <id> | --all) [flags]

Closing an outgoing session ends this node’s access, telling the host when it can; closing an incoming one cuts off whoever is connected from that node, which finds out at its next use.

Flags

Flag	Default	Description
`--all`		close every session open, both ways
`--id <id>`		id of the session

exactly one of --id or --all

Examples

# Close one session
wdx hub session close --id sess-1a2b3c4d5e6f7a8b

# Close every one, from a script
wdx hub session close --all --json

Output

The sessions closed, as they were. With --json: {“result”: “closed”, “session”: {…}}, or “sessions”: […] with --all

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

Errors

Code	Exit	When
`daemon_unavailable`	3	the daemon is not running or not answering
`session_not_found`	1	no session of this id is open
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx hub session list

List the sessions open into this node and from it.

wdx hub session list [flags]

It asks no hub: the sessions are this node’s own.

Examples

# Every session open
wdx hub session list

# As JSON
wdx hub session list --json

Output

The sessions, by when they opened. With --json: {“sessions”: […]}

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 hub session open

Open a session into another node of your account, with its code.

wdx hub session open --node <name> [--code <code>] [flags]

The code is the one your authenticator app shows for that node (wdx hub code setup there); without --code it is asked for, and --json needs it. A code opens one session, and is never logged. After a wrong code, the next try waits, from 1 second doubling to 5 minutes. With a session into the node open already, nothing is asked.

Flags

Flag	Default	Description
`--code <code>`		the node’s authenticator code now; asked for when not given
`--node <name>`		name of the node to open a session into

--node is required
with --json: one of --code

Examples

# Open a session into the desktop, typing its code
wdx hub session open --node desktop

# From a script
wdx hub session open --node desktop --code 492817 --json

Output

The session. With --json: {“result”: “opened”, “session”: {…}}

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

Errors

Code	Exit	When
`code_not_set_up`	1	no authenticator code is set up on the node
`code_wrong`	1	the code is wrong, used already, or came too soon after a wrong one
`daemon_unavailable`	3	the daemon is not running or not answering
`hub_unreachable`	3	the hub cannot be reached, or did not answer as a hub does
`hub_version_unsupported`	1	the hub serves no version of the API this wdx speaks
`node_key_mismatch`	1	the node showed a key other than the one pinned for it in an earlier session
`node_not_found`	1	the account has no node of this name or id
`node_offline`	1	the node is not connected to the hub, or did not answer in time
`node_version_unsupported`	1	the two nodes speak no version in common between them: update the older
`not_logged_in`	1	this node is not logged in to a hub, or the hub cut it off
`remote_access_off`	1	the node allows no sessions: hub.remote_access is off there
`session_closed`	1	the host closed the session: it went idle, its daemon restarted, remote access went off, the hub cut a node off, or it was closed
`too_many_streams`	1	the account has as many streams open through the hub as it may
`usage`	2	the request, command line or a setting is invalid
`internal`	3	an unexpected failure: database, filesystem or git

wdx hub status

Show this machine’s login to a hub and its connection.

wdx hub status [flags]

The connection is connected, connecting, offline (lost, and tried again), logged_out, revoked (another node removed this one) or disabled (the hub’s admin disabled the account). Not being logged in is a state, not an error.

wrong_codes counts the wrong codes other nodes tried since the last session opened into this one, with the time of the latest: a warning line when any.

Examples

# Whether this machine is connected
wdx hub status

# As JSON
wdx hub status --json

Output

The state on the first line, then what to do about it. With --json: {“hub”: {…}}

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