Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Dojo Tools

Below are the various generators, threads and other tools included with the %base desk and usable in the dojo. These are organized into rough categories for convenience.

These may be invoked in one of three ways:

  • + means a generator (standalone computation) which changes nothing in the system

  • | means a “Hood” generator which may make changes to the system

  • - means a thread

Apps and updates

These tools are for managing desks, apps and updates. Install, uninstall, suspend, resume, pause updates, etc.

+gall/agents

Print out the status of Gall agents on a desk.

Agents may either be archived or running. Nuked or unstarted agents which are not on the manifest are omitted.

Arguments

desk

Example

> +gall/agents %landscape
status: running   %hark-system-hook
status: running   %treaty
status: running   %docket
status: running   %settings-store
status: running   %hark-store

|bump

Apply a kernel update.

If %zuse's kelvin version has decreased, try to apply the update. If any desks are incompatible with the new %zuse version, they'll be suspended pending a compatible update.

Examples

Try to apply update, suspending any incompatible desks:

|essential-desk

Mark a desk as essential, or unmark it.

An essential desk is one the system will not suspend when a kernel update arrives. Non-essential desks whose kelvin set does not include the incoming %zuse are suspended so that the update can proceed; essential desks are left running. The current setting is shown as the essential desk field in +vats output.

Arguments

Both arguments are positional: the desk, then a loobean — & to mark the desk essential, | to unmark it.

Examples

|install

Install a desk, starting its agents and listening for updates.

If it's a remote desk we don't already have, it will be fetched. The agents started will be those specified in the desk.bill manifest. If it has a docket file, its tile will be added to the homescreen and its glob fetched. If we already have the desk, the source for updates will be switched to the ship specified.

It takes a $ship and $desk as its mandatory arguments. The desk may be installed with a different name specified in the optional .local argument.

Arguments

Examples

|nuke

Shut down an agent and permanently delete its state.

The default behaviour is to shut down the specified Gall agent and discard its state, similar to the now-deprecated |fade generator. Note this irreversibly wipes the app's state. Additionally, if the optional $desk argument is %.y, it takes a desk rather than an agent name and nukes every agent on the specified desk.

Arguments

=hard & skips the confirmation prompt and nukes immediately. Since |nuke irreversibly discards agent state, this flag removes the only safeguard against a mistyped agent or desk name; use it only in scripts where you have already verified the argument.

Examples

Nuke a single agent:

Nuke every agent on a desk:

|ota

Set the source of updates for the %base desk (the kernel and core apps) to the specified ship. Automatic updates will be enabled, and any new updates available will be fetched and installed.

Arguments

Examples

|ota ~marzod is equivalent to |install ~marzod %kids, =local %base.

|pause

Pause updates on a desk.

The specified desk will stop tracking updates from its upstream source.

Arguments

Examples

|rein

Adjust the state of a desk.

This allows you to stop and start agents on a desk, regardless of whether they're on the manifest. Stopped agents have their states archived. It can also suspend and revive the whole desk with the optional liv argument.

Arguments

Examples

Start an agent:

Stop an agent, archiving its state:

Stop one agent, start another:

Suspend a desk:

Revive a desk:

|revive

Revive all agents on a desk, migrating archived states.

All agents specified in desk.bill which are suspended will be restarted. If updates to the agents have occurred since their states were archived, they'll be migrated with the state transition functions in the agent. This generator does the same thing as selecting "Resume App" from the app tile's hamburger menu.

Arguments

Examples

|start

Start an agent.

Arguments

This first $term is mandatory, the second is optional. If two terms are provided, the first is the desk and the second is the agent on that desk to start. If only one term is provided, it's the name of the agent, and the desk is inferred to be the current desk (typically %base).

Example

|suspend

Shut down all agents on a desk, archiving their states.

The tile in the homescreen (if it has one) will turn gray and say "Suspended" in the top-left corner. This generator does the same thing as selecting "Suspend" from an app tile's hamburger menu.

Arguments

One or more desks may be given; they are all suspended together.

Examples

|uninstall

Uninstall a desk, suspending its agents and ignoring updates.

The specified desk will be retained in Clay, but its agents will all be stopped and have their states archived like |suspend. This is the reverse of |install.

Note that this will not remove the tile or glob from the homescreen, so if the desk has a tile it should be uninstalled with the "Remove App" button in the tile's hamburger menu.

Arguments

Examples

+vats

Print out the status of each installed desk.

To print the status of a single desk rather than all desks, pass the desk name: +vats %base.

By default the output is terse. Passing =verb & prints the full detail.

Fields shown in the default (terse) output:

  • /sys/kelvin - The kernel version(s) the desk is compatible with.

  • %cz hash ends in - The last five characters of the desk hash.

  • essential desk - yes or no; whether the desk is marked essential and so survives a kernel upgrade without being suspended. See |essential-desk.

  • app status - One of running, suspended, or suspended until next update.

  • source ship - The ship the desk updates from, or ~ for a local desk.

  • pending updates - Updates waiting to be applied due to kernel incompatibility.

  • /desk/bill - The desk's agent manifest, or missing if the desk has no desk.bill.

Passing =verb & replaces %cz hash ends in and /desk/bill with the following additional fields:

  • %cz hash - The full hash of the desk.

  • base hash - The merge base (common ancestor) between the desk and its upstream source.

  • force on - The set of agents on the desk which have been manually started despite not being on the desk.bill manifest.

  • force off - The set of agents on the desk which have been manually stopped despite being on the desk.bill manifest.

  • publishing ship - The original publisher if the source ship is republishing the desk.

  • updates - Either local or remote. Local means it will receive updates via commits on the local ship; remote means it will receive updates from the source ship.

  • source desk - The desk on the source ship.

  • source aeon - The revision number of the desk on the source ship.

  • kids desk - The desk published to the ship's children, if any.

Arguments

All arguments are optional.

The positional argument is a list of desks; with none, every desk is reported. Note that the filter is a named argument — +vats %suspended is parsed as a desk named %suspended and reports desk does not yet exist: %suspended.

  • =filt %running: desks that are installed and running.

  • =filt %suspended: suspended desks only.

  • =filt %exists: desks that exist.

  • =filt %exists-not: desks we should have but don't yet.

  • =filt %blocking: desks blocking a kernel update due to incompatibility. This filter always reports all matching desks, even if a desk list was also given.

If both a desk list and a filter are given, the output is the desks in the list that also match the filter — except for %blocking, as noted above.

Examples

Print all desks (default, terse):

Print a single desk with full detail:

Print only suspended desks. Note that the filter must be given as the named argument =filt; a bare +vats %suspended would look for a desk called %suspended and report desk does not yet exist: %suspended.

+trouble

Print out the status of each installed desk.

This is a synonym for +vats.

Example

See +vats.

Azimuth

Tools for managing PKI updates from Azimuth.

+azimuth/block

Print the most recent Ethereum block that has been processed.

This is a good way to check if your ship's somehow got behind on PKI state. If the block printed is substantially behind the most recent Ethereum block, it indicates a problem. Note it's normal for it to be a little behind.

Example

:azimuth|listen

Add a source for PKI updates for a list of ships.

Sets the source that the public keys for a set of ships should be obtained from. This can either be a Gall agent that communicates with an Ethereum node as in the case of galaxies, stars, and planets, or a ship, as in the case of moons.

Arguments

Either:

Or:

The list of ships are those for which you want Azimuth updates from the specified source. The source is either a ship (%ship ~sampel) or an agent (%app %some-agent).

Example

-azimuth-load

Refetch and load Azimuth snapshot.

Example

+azimuth/sources

List all Azimuth sources.

This will print a state-eth-node:jael structure. Its contents is mostly other ships who are sources for updates about moons, but it will also include %azimuth.

Example

:azimuth|watch

Change node URL and network for Azimuth.

Arguments

The first argument is the note URL in a cord like 'http://eth-mainnet.urbit.org:8545' . The second argument specifies the network.

Example

CLI Apps

These commands are for managing the dojo and other CLI apps.

:dojo|acl

Show which ships you've allowed remote access to your dojo.

Example

:dojo|allow-remote-login

Allow a ship to |dojo/link your dojo.

Arguments

The ship you want to allow remote access.

Example

Allow ~bus to link ~zod's dojo:

Link ~zod's dojo on ~bus:

:dojo|wipe

Clear the dojo's subject.

This will clear all values pinned to the dojo's subject with commands like =foo 42.

Example

:dojo|revoke-remote-login

Revoke permission for a remote ship to |dojo/link your dojo.

Arguments

The ship whose permission you wish to revoke.

Example

|dojo/link

Connect a local or remote CLI app.

Note a ship's moons can automatically link its dojo, but other ships require explicit permission with :dojo|allow-remote-login.

Arguments

The $ship is optional, it's only necessary if the app is on a remote ship. The $term is mandatory, and is the name of the CLI app to connect.

Example

Connect to the dojo on a remote ship (this is only possible if you have permission):

Connect to the %chat-cli app locally:

Note you can cycle between CLI apps with Ctrl+X. You can disconnect a CLI app with the |dojo/unlink command.

|dojo/unlink

Disconnect a local or remote CLI app.

Arguments

The $ship is optional, it's only necessary if the app is on a remote ship. The $term is mandatory, and is the name of the CLI app to disconnect.

Example

Disconnect the local %chat-cli app:

Disconnect from a remote dojo session:

Developer tools

These tools are mostly useful to developers or similarly technical people.

.

Make a jamfile and write to disk. A noun is jammed and then written to pier/.urb/put/path/extension using a %sag %blit, saving it as a jamfile.

Arguments

Example

This command is often used for writing pills to disk - see e.g. +pill/solid.

You can also jam arbitrary nouns, e.g.

This is the Nock formula for decrement. If you copy it from /pier/.urb/put/decrement.atom to pier/base then you can run it by scrying it from Clay and running +cue to reobtain the formula.

@

Write atom to a file in binary.

Arguments

Example

will create a file called test.atom in pier/.urb/put/test.atom. The contents of this file is a binary representation of the atom, 1111011.

+ames/flows

Print details of Ames flows by ship.

Arguments

This argument is optional:

If no argument is provided, it will print details of Ames flows for all ships, sorted by the number of flows. If a number n is provided as an argument, it'll only print the top n results.

Example

All flows:

Top 2 ships:

|ames/prod

Reset congestion control; re-send packets immediately.

Ames uses a backoff algorithm for congestion control. This can be inconvenient when debugging in certain cases, you may have to wait a couple of minutes before an unacknowledged packet is re-sent. This generator resets congestion control, causing at least one pending packet to be immediately re-sent for each flow.

Arguments

If no argument is given, congestion control will be reset for all flows. Otherwise, you can specify a number of $ships, and congestion control will only be reset for flows to those ships.

Example

|ames/sift

Filter Ames debug printing by ship.

This filters the output controlled by |ames/verb.

Arguments

If no argument is given, filtering is disabled. Otherwise, Ames debug printing will be filter to only include the specified ships.

Example

Enable filtering:

Disable filtering:

|ames/snub

Blacklist/whitelist ships in Ames.

All packets from either the blacklisted ships or all non-whitelisted ships (as the case may be) will be dropped.

Arguments

(Either %allow or %deny then a list of ships.)

  • %allow or %deny set whether the following ships are a whitelist or blacklist.

Note that while %deny is ordinary blacklist blocking, %allow means any ships not on the list will be blocked.

Note also that this generator totally overrides existing snub settings - it doesn't just add or remove ships from an existing list.

Example

Create a blocklist:

Create a whitelist (and therefore block everyone else):

+ames/timers

Print Ames message-pump timers by ship.

Arguments

If no argument is provided, it will print details of Ames timers for all ships, sorted by the number of timers. If a number n is provided as an argument, it'll only print the top n results.

Example

Print all the Ames timers for all ships:

Print the top two ships:

|ames/verb

Enable verbose Ames debug printing.

Arguments

A $verb:ames is one of %snd, %rcv, %odd, %msg, %ges, %for, or %rot. Each one enables printing of different kinds of events. You can enable as many as you want at one time. If |ames/verb is given no argument, it disables all Ames debug printing.

For details of the meaning of these $verbs, see its entry in the Ames Data Types documentation.

Example

|ames/wake

Clean up Ames timers.

Set timers for Ames flows that lack them, cancel timers for Ames flows that have them but shouldn't.

Example

|ahoy/prob

Migrate one peer to Directed Messaging (Mesa).

Negotiates with the given ship to move networking with it from %ames to %mesa. Sends a %ahoy-prob poke.

Arguments

  • The positional argument is the peer to migrate.

  • =force-test retries the negotiation even if we previously recorded that the peer does not support directed messaging. Defaults to &.

Example

|ahoy/comb

Migrate all peers to Directed Messaging (Mesa).

Sends an %ahoy-comb poke.

This is currently a no-op. The handler in /lib/hood/ahoy.hoon begins ?: & this :: XX disabled, so the poke succeeds and does nothing. Use |ahoy/prob for an individual peer.

Arguments

All default to &. =dry is a test run, =veb is verbose output, and =nuke clears the recorded per-peer negotiation state first.

|mate

Migrate peers to Directed Messaging locally, without negotiating.

Sends a %helm-mass-mate poke. Unlike |ahoy/prob, this skips the negotiation step, so the peer is not consulted. For testing only — the generator always runs dry.

Arguments

A specific ship, or ~ for all ships.

|rege

Negotiate a peer back from Directed Messaging to ordinary Ames.

The inverse of |ahoy/prob. Sends a %helm-send-rege poke.

Arguments

=dry defaults to &, so it is a test run unless you pass =dry |.

Example

|ress

Regress peers to ordinary Ames locally, without negotiating.

Sends a %helm-mass-rege poke. The bulk counterpart to |rege, skipping negotiation. For testing only — always runs dry.

Arguments

A specific ship, or ~ for all ships.

+pill/brass

Build a brass pill.

A brass pill is a complete bootstrap sequence that recompiles the vanes, unlike a +pill/solid pill which does not.

Arguments

The first argument is the desk to be used as "base", containing the kernel etc. Any extra desks are optional.

The base desk may alternatively be specified as a path to a /sys directory including the path prefix like /=some-desk=/foo/bar/sys. In that case, the path prefix from that path will be used to determine the base desk. This is only useful if you want the start-up events in the pill to use an alternative compiler or Arvo source.

Example

Export a brass pill containing just the %base desk:

The pill will now be available in <pier>/.urb/brass.pill in the host filesystem.

Export a brass pill with multiple desks:

-build-cast

Build a static mark conversion gate.

Arguments

The path is of the format %/from-mark/to-mark. It must being with the path prefix denoting the desk that contains the specified mark files.

Example

-build-file

Build a Hoon file.

Arguments

The path points to a Hoon file in Clay It must begin with the path prefix.

Example

-build-mark

Build a dynamic mark core.

A dynamic mark core is one that deals with $vases rather direct values. Its type is a $dais:clay.

Arguments

The path is a path prefix followed by the mark, like %/txt. The mark in question must exist in the desk specified by the prefix.

Example

-build-nave

Build a static mark core.

A static mark core is one that deals with values directly rather than vases. Its type is a $nave:clay.

Arguments

The path is a path prefix followed by the mark, like %/txt. The mark in question must exist in the desk specified by the prefix.

Example

-build-tube

Build a dynamic mark conversion gate.

A dynamic mark conversion gate is one that deals with $vases rather that plain nouns. Its type is a $tube:clay.

Arguments

The path is of the format %/from-mark/to-mark. It must being with the path prefix denoting the desk that contains the specified mark files.

Example

+dbug

Query the state or bowl of a running agent.

Arguments

See the dbug section of App School lesson 3 for details of the positional argument.

The named =depth argument addresses an agent running underneath a wrapper agent. With a non-zero depth the poke is wrapped as [%skip depth poke], and each layer of /lib/dbug decrements it before passing the poke down. It is only meaningful for a nested agent; sending it to an ordinary agent produces unexpected poke to %agent with mark %dbug.

Example

This is only used with an :agent, not by itself.

|eyre/clean

Delete stale incoming HTTP subscriptions.

Eyre channel subscriptions can be left behind when a channel goes away without its subscriptions being torn down. This generator finds those and can remove them.

It runs in dry mode by default, only reporting how many stale subscriptions it found. Pass =dry | to actually delete them.

Arguments

  • =dry - defaults to & (dry run). Pass | to delete.

  • =veb - verbosity. %1 prints each stale subscription; %2 prints each subscription that still exists.

Examples

|gall/sear

Clear pending $move queue from a ship.

Arguments

The ship from which queued moves should be cleared.

Example

|gall/sift

Set Gall verbosity by agent.

This filters the debug output toggled by |gall/verb.

Arguments

If agents are specified, debug prints will be filtered to only those agents. If no arguments are given, filtering will be disabled.

Example

Filter to just these agents:

Disable filtering:

|gall/verb

Toggle Gall debug printing.

Arguments

If the %odd argument is provided, Gall will print debug information about errors like duplicate %watch acks, subscriptions closing due to an agent crashing on a %fact, etc.

If no argument is given, such debug printing will be disabled.

Example

Turn on error messages:

Turn off error messages:

|pass

Pass a task to a vane.

Warning

This is a powerful command and has the potential to break things if you're not careful.

Arguments

A $note-arvo is defined in /sys/lull.hoon as:

It's a vane letter (%a for Ames, %b for Behn, etc) followed by one of that vane's tasks.

Note that you can't receive any gifts in response.

Example

Run -hi our "foo" via Khan:

Pass a %text task to Dill:

-read

Read a file, local or remote.

While +cat can only read text files, the -read thread can read any kind of file, directory or desk on any ship it has permission to read. This thread doesn't pretty-print the result like +cat, it just produces the data.

-read isn't limited to ordinary file reads, but can make requests using any care Some $cares might be useful, such as %u to check file existence. Others have obscure technical uses. The most common is %x, which is a normal read.

Arguments

  • care One of %a %b %c %d %e %f %p %r %s %t %u %v %w %x %y %z, denoting a Clay submodule. For details of their meaning, see the Clay data types documentation and Clay scry reference.

  • ship The target ship like ~sampel, or our for the local ship.

  • desk The desk like %base.

  • case The revision you're requesting. This can be one of:

    • ud+123 - A revision number.

    • da+now - The revision at that date-time. You can use now for the most recent or a @da for another time.

    • tas+foobar: A revision label, these are rarely used.

  • path The filepath like /gen/code/hoon. Note the Clay path prefix is not included since that data was specified separately.

Example

Read sys.kelvin in the %base desk on the local ship at the current revision:

Check for the existence of that same file:

|eyre/serve

Bind a generator to a URL path.

See the Eyre Guide for details of writing web-facing generators.

Arguments

The first path is the URL path to bind like /foo/bar/baz. The second $path is the path to the generator in $desk like /gen/who/hoon (note it does not include the path prefix).

Example

Bind /gen/who/hoon in the %base desk to the /who URL path:

In a Unix terminal, try requesting it:

+pill/solid

Build a solid pill

A solid pill is a partial +pill/brass pill, it doesn't recompile the vanes and so boots faster. It is intended for development purposes, not production.

Arguments

The first argument is the desk to be used as "base", containing the kernel etc. Any extra desks are optional.

The base desk may alternatively be specified as a path to a /sys directory including the path prefix like /=some-desk=/foo/bar/sys. In that case, the path prefix from that path will be used to determine the base desk. This is only useful if you want the start-up events in the pill to use an alternative compiler or Arvo source.

Example

Export a solid pill containing just the %base desk:

The pill will now be available in <pier>/.urb/solid.pill in the host filesystem.

Export a solid pill with multiple desks:

-test

Run tests for a library.

Arguments

Each path is a path to a file to test, and must include the path prefix.

Example

Refer to the Unit Test Guide for details of using the -test thread.

+behn/timers

Print out currently running Behn timers.

Examples

Filesystem (Basic)

These are basic tools for things like copying files, navigating directories, etc.

+cat

Read a file at the given location and print its contents in the dojo.

If the specified path points to a directory rather than file, it will list the files in that directory like the +ls command documented below.

+cat can only print text-based files like .hoon source-code, .txt, .html, etc. It won't work for binary blobs or other non-text files.

Arguments

The $path is mandatory, the $vane is optional.

The past must include a path prefix.

It can query Gall agents rather than Clay files if the optional , =vase %g argument is given. In that case, it will perform a %gx scry to the given scry path. The type returned must be some kind of text file, either a @t or a $wain (a (list @t)). Most agents do not have scry endpoints that produce text files so the %g feature is rarely useful.

Example

Read a hoon file:

List the files in a directory:

|cp

Copy a file.

Arguments

The first path is to the file and the second is where to copy it.

Both the input and output paths must include the full path prefix.

The output path must end with an explicit filename and mark you can't just point it at a directory.

Example

Copy the code.hoon generator to the root of %base with the name foo.hoon:

Let's list the files in the root of %base:

=dir

Change working directory.

Note this is not a generator or thread as are most other tools documented. Rather, it is a special command built directly into the dojo.

Arguments

The path must include the path prefix.

If no path is specified, it will switch back to the default location (the root of the %base desk at its most recent revision).

Example

Let's try changing to the root of the %landscape desk

The dojo prompt will now look like:

% and /=== now resolve to this location, so any commands like +ls %, +tree %, etc, will be run against this location.

The working directory doesn't need to be the root of a desk, you can also do =dir /=base=/gen/hood, etc.

If you specify a different case in the path prefix like =dir /=base/1, you will switch to that revision.

To switch back to the default location (the root of the %base desk at its most recent revision), you just run =dir without an argument.

+ls

List files and directories at the specified location.

Arguments

The $path is mandatory, the $vane is optional:

The path must include the path prefix.

The default behavior of +ls is to query Clay, but Gall agents can also be queried by specifying the optional =vane %g argument like +ls /=some-agent=/foo/bar, =vane %g. This will perform a scry of the form .^(arch %gy /=some-agent=/foo/bar). Very few Gall agents implement %y scry endpoints that produce $arch types, so this feature is almost entirely useless.

Example

Note the mark (file type/extension) is separated with a / rather than a . as is common in other systems: /hoon is not a sub-directory of /ames here, it is the mark. Directories can be distinguished from files by their lack of a mark; they'll just look like app/.

+mv

Move a file from one location to another.

Arguments

The first path is to the file and the second is where to move it.

Both paths must include the path prefix.

The output path must end with an explicit filename and mark you can't just point it at a directory.

Example

Create a file:

Move it:

|rm

Delete a file.

Note you cannot delete a directory, but a directory will be disappear once all its files are gone.

Arguments

The path must include the path prefix.

Example

Create a file:

Delete it:

+tree

Display all files in the given directory and its sub-directories.

Arguments

The path must include the path prefix.

Example

Filesystem (Advanced)

These are more advanced desk and filesystem tools.

|clay/autocommit

Enable automatic commits for a mounted desk

Auto-commits can be disabled with |clay/cancel-autocommit.

Arguments

Example

In the dojo:

In a separate Unix shell session:

Back in the dojo:

|clay/cancel-autocommit

Cancel automatic commits for all mounted desks

Note this will cancel automatic commits for all desks, it's not possible to target a single desk.

Examples

|commit

Commit changes to mounted desk

Arguments

The $desk is mandatory, the .auto is optional.

If .auto is %.y, auto-commits will be enabled, meaning changes to that desk on the host side will automatically be committed as soon as they happen.

Auto-commits can be disabled with |clay/cancel-autocommit.

Example

In the dojo:

In a separate Unix shell session:

Back in the dojo:

|clay/fuse

Perform an octopus merge.

A %fuse request in Clay replaces the contents of %destination-desk with the merge of the specified $beaks according to their merge strategies. This has no dependence on the previous state of %dest so any commits/work there will be overwritten.

|clay/fuse extends this concept with the idea of a tracked source. When specifying beaks to include in your fuse, specify %track instead of a case This will tell |clay/fuse to retrieve the latest version of the source beak and to rerun the %fuse request whenever that tracked source changes. A fuse can have many tracked sources, or none. The base may be tracked as well.

Arguments

Either:

Or:

The first argument is the target $desk that will be overwritten. After that is either %cancel to cancel an existing tracked fuse, or else a $path followed by a series of [germ path]. The first $path is a $beak like /~zod/foo/track or /~zod/foo/5, and is the base of the octopus merge. For the remaining [germ path], the $germ is the merge strategy (for details run |merge without arguments and read the help text it prints), and the $path is another $beak.

The optional .overwrite flag allows you to overwrite a currently ongoing fuse. Without this flag, attempting a fuse into a desk that you already |clay/fuse'd into will error.

For usage details, you can run |clay/fuse without arguments and it'll print out a help text.

Examples

|clay/fuse-list

Print tracked fuse sources for a desk.

See the |clay/fuse command for details.

Example

|label

Add a label to a desk revision.

Labels let you name particular commits, and then refer to them by that name rather than date or revision number.

Arguments

The $desk and $term are mandatory, the .aeon is optional. The $term is the label to give the revision. If an $aeon is not specified, it will default to the most recent revision.

Example

|merge

Merge one desk into another.

Arguments

The first $desk is the local merge target. The second $desk is the merge source on the specified $ship. The optional .cas argument specifies a particular case (revision reference) like ud+5, da+now, etc. The optional .gem argument specifies a merge strategy. The default merge strategies is %auto, which does a fast-forward %fine merge if the target desk exists, and creates a new desk with %init if not.

For details of usage and all the different merge strategies, run |merge without arguments for a help text.

Example

|mount

Mount a desk or directory to the host filesystem.

Arguments

A whole desk:

A directory:

If it's a path it must include the full path prefix.

Note you can't mount a single file directly.

Example

Mount the whole %base desk:

The desk is now accessible at <pier>/base in the host filesystem.

Mount the /gen directory of the %base desk:

The /gen directory is now accessible at <pier>/gen in the host filesystem.

|new-desk

Create a new desk either from a blank template or from an existing desk.

Arguments

The first $desk is the name of the desk to be created. The optional .from is the source desk if present. The optional .hard specifies whether to overwrite an existing desk of the same name. The optional .gall specifies whether to include common Gall support files like /lib/skeleton.

Example

Create a new desk:

The desk is now created in Clay.

Create a new desk, reading the template files from a desk other than the default:

=from selects which desk the template files are read from; it does not copy that desk. |new-desk always writes the same short, fixed file list — /mar/noun/hoon, /mar/hoon/hoon, /mar/txt/hoon, /mar/kelvin/hoon and /sys/kelvin, plus the extra Gall files if =gall & is given — and =from only changes where those files are sourced. The default is already %base, so the command above is equivalent to a bare |new-desk %pahoehoe.

For comparison, on a fresh ship %base contains {app sur gen lib mar ted desk sys}, while a desk created this way contains only {mar sys}.

Create a new desk, overwriting any existing desk and including useful Gall files:

The desk is now created in Clay.

|clay/norm

Add a tombstone policy rule.

Note that the policy will not be automatically applied when set, you'll need to run |pick for the garbage collection to occur.

Arguments

The path is to a file or directory on the given $desk on the given $ship. The ? is %.n if it should be tombstoned, %.y if it should be kept.

Examples

+clay/norms

Print tombstone policies for all desks.

Example

%.y means old revisions of the file or directory will be kept, %.n means they'll be tombstoned.

|pick

Apply tombtoning policies; collect garbage.

Example

|private

Make a desk directory or file private (prevent remote ships from reading it).

Note that if a desk or directory is publicly readable, making any directories or files inside of it private will prevent remote ships from syncing the entire desk/directory. They'll still be able to read the individual parts that aren't private though, just not the whole thing.

Desks, files and directories can be made publicly readable again with |public.

Arguments

The $desk is mandatory, the path is optional. If specified, the $path is a directory or file in the given desk.

Example

|public

Make a desk directory or file publicly readable (allow remote ships to read it).

Things can be made private again with |private.

Arguments

The $desk is mandatory, the path is optional. If specified, the $path is a directory or file in the given desk.

Example

|sync

Continuously merge into local desk from another local or remote desk.

Every change on the source desk will be merged into the local one. This tracking can be stopped with |unsync.

Arguments

The first $desk is the local target, the second is the source on the specified $ship.

Example

|syncs

List currently active desk syncs.

Example

|tomb

Tombstone a file at a particular revision.

Tombstoning means deleting a file's data in an old revision in Clay only leaving the file reference.

This can only tombstone a single file, it cannot recursively tombstone a directory. If a directory is specified, it will fail.

The desk revision number specified cannot be the current revision, it must be an old one. This will only tombstone the file at the specified revision, not any revisions before it.

Note this will also execute any other unapplied tombstone policies as it sends Clay a %pick garbage collection task.

Arguments

The path is mandatory, it's a path to a file including the full path prefix. If the optional .dry argument is %.y, it will perform a dry run and not actually tombstone the file.

Examples

|unmount

Unmount a previously mounted desk or directory.

Note that any uncommitted changes on the host side will be discarded.

Arguments

If the thing you're unmount is a desk you'll just specify the desk name. If it's a sub-directory of a desk, you must specify the mount-point, which is whatever the directory is called in the host filesystem. For example, if you mounted %/gen and it's at <pier>/gen, you'd specify %gen here.

Example

Unmount the %base desk:

|unsync

Stop syncing a desk with another.

Arguments

The first $desk is the local one receiving updates, the second $desk is the source for updates on the specified $ship.

Example

Miscellaneous

Miscellaneous utilities.

+hello

Hello, world.

Arguments

Example

+help

Display information about generators.

Arguments

Examples

Show help message for all generators in %base:

Show help message for a specific generator in %base:

|hi

Ping another ship with an optional message.

The hi and message will be displayed in that ship's dojo. This is useful for testing connectivity.

Arguments

The target $ship is mandatory, the $cord is an optional message.

Example

Without a message:

With a message:

Print out the sponsor of this ship.

Examples

+keys

Print the $life (key revision number) and $rift (continuity number aka factory reset number) for a ship.

Arguments

Example

Moons

These tools are for spawning and managing moons.

|moon

Spawn a new moon.

Arguments

All arguments are optional. If the $ship is not specified, it'll spawn a random moon. If it's specified, it will spawn the given moon.

If .public-key is specified, it'll configure the moon with the given public key rather than generating a new key pair. This is useful if your planet has breached and forgotten about its moon.

If spawning a new moon, it will spit out the moon's private key, a long code which looks like 0wn6bMe.l1....... You can copy this and save it in a .key file, then give the key file as an argument to the runtime when booting the moon like:

You can also give the runtime the key directly by using -G rather than -k.

Example

Spawn a random moon:

Spawn a specific moon:

Register an existing moon with the given public key:

|moon-breach

Breach (factory reset) a moon.

This is run on the moon's parent planet. Note that breaching a moon will require to you boot it from scratch with its original keys. Breaching a moon, unlike a planet, will not change its keys. If you no longer have its original keys you'll also need to run |moon-cycle-keys to generate new ones.

Arguments

The $ship is mandatory, it's the moon to breach. The .rift is optional, it's the continuity number (factory reset number). You'd specify a .rift if you'd factory reset the parent planet and need to skip ahead to a particular rift to match the existing moon. Note you can't turn the rift backwards, only forwards.

Example

|moon-cycle-keys

Change the keys of a moon.

This is run on the moon's parent. Once you've cycled the moon's keys on its parent, you'll need to run |rekey on the moon itself with the new keys that are printed.

Arguments

The $ship is mandatory, it's the moon to rekey. The .life and .public-key are optional.

You'd only specify a .life if you needed to jump ahead to a particular key revision. You'd only specify a .public-key if you need the moon to have a particular public key. The only time you'd need either of these optional arguments is if you've breach the moon's planet and need to get it back in sync with the existing moon. Note you can only go forward with the .life, not backwards.

Example

Change the keys for a moon:

The long code beginning with 0w1.Nq... are its new private keys. You'd give that code to the |rekey command on the moon itself.

Rekey to a specific $life (key revision):

Rekey to a specific $life and with a specific public key:

Spider

Tools for interacting with threads and Spider.

:spider|kill

Kill all running threads.

Example

:spider|poke

Poke a running thread.

Arguments

The @ta is a thread ID of a running thread. The $mark and $vase are the data to poke the thread with.

:spider|start

Start a thread.

Arguments

The $term is mandatory, it's the name of a thread in /ted in the current desk. The $vase is optional, it's the start arguments for the thread if needed.

Note this tool looks for the thread in the current desk, so you'll have to change desk with =dir if you want to run one elsewhere.

Example

:spider|stop

Stop a running thread.

Arguments

The @ta is a thread ID of a running thread.

+spider/tree

List all currently running threads.

Example

System

System information and management tools.

|automass

Print memory reports periodically.

Automatic memory reports can be cancelled with |cancel-automass.

Arguments

A @dr is a relative time, for example ~s30, ~m5, ~h1, ~d1, ~d1.h1.m5.s30, etc.

Example

Thirty seconds later:

(and every thirty seconds after)

|cancel-automass

Cancel periodic memory reports (enabled by |automass).

Example

+code

Print out your web login code.

Example

|code

Change your web login code.

You'll be logged out of all existing web sessions when you change the code.

Note that bridge.urbit.org won't be able to automatically derive your web login code if you change it.

Arguments

With the %reset argument, the web login code will be changed. With no argument, it'll just print out your existing code and code revision number.

Example

With no argument:

With the %reset argument:

-code

Print out your web login code (with leading ~).

Example

|eyre/cors/approve

Approve a CORS origin.

Arguments

The argument is a cord containing the origin to approve.

Example

+eyre/cors/registry

Print approved, rejected and requested CORS origins.

Example

|eyre/cors/reject

Reject a CORS origin.

Arguments

The argument is a cord containing the origin to reject.

Examples

-dns-address

Request a <ship>.arvo.network subdomain and configure SSL.

Note this only works for stars and planets. Note your ship must be accessible on port 80.

If successful, you'll be able to access your ship's web interface at https://<ship>.arvo.network.

Arguments

The @if is a public IPv4 address in the format .x.x.x.x like .192.168.1.254.

Example

|exit

Shut down this ship.

Example

|knob

Adjust vane error verbosity.

Note this only applies to %crud error messages that look something like:

Arguments

The $term is an error tag like %foo. The verbosity level for the specified tag may be one of:

  • %hush - Completely silent, print nothing.

  • %soft - Just print crud: %error-tag event failed, ignore any $tang given in the %crud.

  • %loud - Print the %soft message as well as the full $tang given in the %crud task.

Example

Loud:

Soft:

Hush:

|mass

Print a memory report.

Examples

|meld

Deduplicate memory.

Note this can take a large amount of memory to complete if the ship's existing memory footprint is large. If the host OS has limited memory, it may be more efficient to shut down the ship and run it directly from the runtime.

Example

|pack

Defragment memory.

This is lighter than |meld on memory usage but does not compact the ship's state as much.

Example

|rekey

Rotate private keys.

Note this should not be used unless you've changed your network keys on bridge.urbit.org first. Using this incorrectly will render your ship unable to communicate.

Note also this is not for when you perform a factory reset, this is specifically for if you change your keys without a factory reset.

If your ship is a moon you'd do the key change on its parent planet rather than through bridge.urbit.org, and then use |rekey on the moon itself.

Arguments

This is the long code inside the sampel-palnet-1.key file you downloaded from bridge.urbit.org (or the code that your planet printed out in the dojo if a moon). It'll look like 0w9oBR.dfY5Z.LSxut.YHe3u..... You must wrap it in single-quotes when giving it to this generator, like '0w9oBR.dfY5Z.LSxut.YHe3u...'.

Example

|verb

Toggle kernel event tracing verbose mode.

When enabled, this will print a move trace for every event in Arvo.

Example

Toggle on:

Run |verb again to turn it off.

|trim

Trim kernel state.

This command is used to reduce memory pressure. Currently, the only two vanes that do anything with a %trim task are Eyre and Clay. Eyre closes inactive channels and Clay clears its build cache. Typically these things use little memory so the impact of |trim is minimal and it is not useful. For significant memory reduction, see |meld and |pack.

Arguments

You may optionally give a trim priority number as an argument. The lower the number, the higher the priority. Currently, none of the vanes do anything with this so there's no point in specifying it.

Example

PreviousConfiguring S3 Storage
NextFilesystem

Last updated