a bird-brained guide to:

orienting yourself in dojo

being honest, the first several times in an urbit terminal is confusing and frustrating.

it's familiar enough at first glance, but things get strange very quickly. outside of the vim-like denial of typing, mysterious additions to common commands thwart the basic desire to see what is on your computer.

here we'll clarify a few urbit terminal commands so bird-brains like ourselves know where we are and what is available to us in dojo.

first, where are the files and folders?

if you know a little hoon you might know +ls is used instead of ls for listing out file/folders. but if you are inattentive like me you'll have missed that +ls requires an argument. which you'll see is a path.

• try +ls /=base=

now you're looking at the file/folders within your %base desk.

• go deeper with +ls /=base=/app

awesome!

now you're free to go as deep as you wish within the collection of file/folders of your %base desk.

but where are the other desks? how do you see them?

• try +vats

you can also try the equivalent but easier to remember +trouble. either way you'll see:

%webterm
  /sys/kelvin:      [%zuse 416] [%zuse 415]
  base hash:        ~
  %cz hash:         0v3.0chi4.jv46l.iaspp....
  app status:       running
. . . 

this will pop-out a tall list of every desk on your urbit, their %desk-names along with lots of useful info for troubleshooting.

tip for later: if you only need to look at one desk use +vat %desk-name.

now back to navigating thru your urbit

with your +vats list of desks you can now put any %desk-name you see into the +ls command from before.

• try +ls /=webterm=

at this point you might be wondering what the = signs mean. it's a convenience.

• to see what I mean run /===

> /===
[~.~tex ~.base ~.~2023.3.27..22.38.51..18da ~]

dojo will spit out the equivalent of /===, which is a list of your ship-name, the base desk, and the current time/date.

• note: each item has ~. in front, like ~.~tex instead of simply ~tex. this is a knot text type and is used for paths of file/folders. the slashes in /=desk=/folder/file/mark takes care of converting each segment into a knot and creating a path for you.
• tip: for further %base desk convenience you can use the % to do the exact same as /=base= and /===. try +ls % and notice that you are looking into the %base desk.

last thing for now

a file can be recognized because it doesn't end with a /. examples are desk/bill and /=base=/sur/shoe/hoon.

unlike a standard computer that indicates file types with .pdf or .wav, the ending /hoon indicates a hoon file. if you looked at that same file outside of dojo, you'd see shoe.hoon.

with this knowledge for recognizing files you can use +cat to print out a files contents.

• try +cat /=base=/lib/sole/hoon

you should see:

> +cat /=base=/lib/sole/hoon
/~tex/base/~2023.3.27..22.51.31..5a7d/lib/sole/hoon
::
::::  /hoon/sole/lib
  ::
/?    310
/-    *sole
::::
  ::
|_  sole-share                                         
++  abet  +<
++  apply
  |=  ted=sole-edit
  ^+  +>
  ?-    -.ted
    %del  +>.$(buf (weld (scag ...
    %ins  +>.$(buf (weld (scag ...
    %mor  |-  ^+  +>.^$
          ?~  p.ted
. . .

nice!

at this point you can see all the desks and peer deeply into your urbit. but this is only surface level. remember the time/date component of /===. all files know when they are created and saves versions from the past. at any time you can reverse time and see exactly what those desks contained in the stone ages.

look into the clay vane to understand the file system on a much deeper level.

your feathered friend,
bird

more guides