mirror of
https://github.com/ilyakooo0/urbit.git
synced 2024-12-18 04:11:49 +03:00
274 lines
8.8 KiB
Markdown
274 lines
8.8 KiB
Markdown
XX The CLI is under heavy development with, with pieces being folded
|
|
into the "window manager" `sole` and the new cli `dojo`. Don't expect
|
|
any of the following to work as described.
|
|
|
|
This guide is intended to get you oriented in the Arvo command prompt
|
|
and give you a tour of some basic utilities. The command prompt comes in
|
|
two flavors, in a web browser and in a terminal. For the most part
|
|
they're the same, except that in a browser you can evaluate tall-form
|
|
Hoon expressions but you can't run readline apps, such as `:talk`.
|
|
|
|
Every Arvo command prompt is also a Hoon REPL. The command line is a
|
|
great place to test out your hoon knowledge. In this guide we're just
|
|
going to talk about some basic system utilities and get comfortable
|
|
moving around in `%clay`. If you'd just like to see a list of
|
|
command-line utilities, you can find the Arvo man pages
|
|
[here](../arvo/util).
|
|
|
|
This rudimentary tour should work well in both places.
|
|
|
|
1
|
|
|
|
Move around `%clay`
|
|
|
|
After finishing the [setup instructions]() you should have an Arvo
|
|
prompt that looks like this:
|
|
|
|
~talsur-todres/try=>
|
|
|
|
The path at the beginning of your prompt is actually a path in the
|
|
global filesystem of Urbit, called `%clay`. Since `%clay` is universal
|
|
across all of Urbit, each full path starts with a ship name. `%clay` is
|
|
also versioned on a per-desk basis. Desks are the top-level directories
|
|
in your pier.
|
|
|
|
Moving around `%clay` is simple. There is no equivalent of `cd`.
|
|
Instead, just type a valid path name at the prompt to move to that
|
|
directory. Here we'll move to our starting root path in the try desk,
|
|
`/try=` to the `main` desk:
|
|
|
|
~talsur-todres/try=> /=main=
|
|
=% /~talsur-todres/main/0
|
|
~talsur-todres/main=>
|
|
|
|
We have two shortcuts in `%clay` that are worth noting, `=` and `%`.
|
|
|
|
`=` copies in some corresponding part of our current path. In the second
|
|
line above you can see how the `=` in `/=main=` pull in the
|
|
`~talsur-todres` and `0` in from our starting directory,
|
|
`/~talsur-todres/try/0`. It's important to note that our full prompt to
|
|
start is `/~talsur-todres/try=`, where the trailing `=` indicates the
|
|
current revision. In the shell, revision `0` never exists — it's used as
|
|
a pointer to the head.
|
|
|
|
`%` is similar to `.` in unix:
|
|
|
|
~talsur-todres/main=> %
|
|
=% /~talsur-todres/main/0
|
|
~talsur-todres/main=> %%
|
|
[~.~talsur-todres ~.main ~]
|
|
~talsur-todres/main=> %%%
|
|
[~.~talsur-todres ~]
|
|
~talsur-todres/main=> %%%%
|
|
~
|
|
|
|
When using `%` to move around in `%clay` you need to make sure to use
|
|
leading and trailing `/` to ensure your path is interpolted correctly:
|
|
|
|
~talsur-todres/main=> /%%%/try=
|
|
=% /~talsur-todres/try/0
|
|
~talsur-todres/try=>
|
|
|
|
2
|
|
|
|
Create some revisions
|
|
|
|
Let's use `:into`, our simple utility for writing text to a file, to
|
|
create a new file:
|
|
|
|
~talsur-todres/try=> :into %/helo/txt 'helo mars'
|
|
written
|
|
~talsur-todres/try=>
|
|
|
|
To confirm that our file was written, we can use `:ls`. `:ls` prints a
|
|
list of directory contents, but requires that you specify a path. `%`
|
|
will suffice for the current path:
|
|
|
|
~talsur-todres/try=> :ls %
|
|
readme helo
|
|
~talsur-todres/try=>
|
|
|
|
Let's quickly switch back to a unix command prompt to see a few things
|
|
about both how files are synced between `%clay` and unix, and where your
|
|
apps live.
|
|
|
|
my-pier/talsur-todres/$ ls try
|
|
helo.txt readme.md
|
|
my-pier/talsur-todres/$ cat try/helo.txt
|
|
helo mars
|
|
|
|
Here you can see that our files are synced back to unix as they are
|
|
changed in urbit, and vice-versa. As you change files in unix you'll see
|
|
those changes appear in `%clay`.
|
|
|
|
my-pier/talsur-todres/$ ls base/app/
|
|
bang grep peek solid tweet
|
|
began helm poke sync twit
|
|
begin hi pope talk twitter-auth
|
|
cat into reboot tease twitter-feed
|
|
code label reload terminal type
|
|
cp ls reset test unsync
|
|
curl matrix rm ticket verb
|
|
dojo mv shell time wipe
|
|
gnab nop sole tree ye
|
|
my-pier/talsur-todres/$ cat base/app/ls/core.hook
|
|
:: ConCATenate file listings
|
|
::
|
|
:::: /hook/core/cat/app
|
|
::
|
|
/+ sh-utils
|
|
// /%%%/ls/subdir
|
|
!:
|
|
::::
|
|
::
|
|
|_ [hid=hide ~]
|
|
++ peer ,_`.
|
|
++ poke--args
|
|
%+ args-into-gate .
|
|
|= [arg=(list path)]
|
|
=- tang/(zing -)
|
|
%+ turn arg
|
|
|= pax=path
|
|
^- tang
|
|
=+ ark=;;(arch .^(%cy pax))
|
|
?^ q.ark
|
|
:- leaf/(spud pax)
|
|
%+ turn (lore ;;(@t .^(%cx pax)))
|
|
|=(a=cord leaf/(trip a))
|
|
?- r.ark :: handle ambiguity
|
|
~
|
|
[rose/[" " `~]^~[leaf/"~" (smyt pax)]]~
|
|
[[@t ~] ~ ~]
|
|
$(pax (welp pax /[p.n.r.ark]))
|
|
*
|
|
=- [palm/[": " ``~]^-]~
|
|
:~ rose/[" " `~]^~[leaf/"*" (smyt pax)]
|
|
`tank`(subdir pax r.ark)
|
|
==
|
|
==
|
|
--
|
|
|
|
Here you can see that `/base/app` is the main location where our apps
|
|
are stored, and the contents of the `:ls` app. urbit applications are of
|
|
course written in hoon, our naitive programming language. Don't worry
|
|
about the contents of the file for now. Since changes in unix are synced
|
|
back in to urbit, we can develop urbit programs by simply editing them
|
|
in our favorite editor and saving them.
|
|
|
|
For the time being let's switch back to urbit and update our file with
|
|
some new content, so we can see how `%clay` stores revisions.
|
|
|
|
~talsur-todres/try=> :into %/helo/txt 'gbye mars'
|
|
written
|
|
~talsur-todres/try=> :ls /=try/1
|
|
readme helo
|
|
~talsur-todres/try=> :cat /=try/1/helo/txt
|
|
/~talsur-todres/try/9/helo/txt
|
|
helo mars
|
|
~talsur-todres/try=> :cat /=try/2/helo/txt
|
|
/~talsur-todres/try/10/helo/txt
|
|
gbye mars
|
|
~talsur-todres/try=> :cat /=try=/helo/txt
|
|
/~talsur-todres/try/~2014.11.26..01.06.33..c93a/helo/txt
|
|
gbye mars
|
|
~talsur-todres/try=>
|
|
|
|
Here we use `:ls` to investigate the filesystem across versions. You can
|
|
see that our `helo` file exists in our first revision. Using the simple
|
|
`:cat` command we can print the contents of `/=try/helo/txt` in its two
|
|
separate, versioned states.
|
|
|
|
We can even move to a different version of our desk and look around:
|
|
|
|
~talsur-todres/try=> /=try/1
|
|
=% /~talsur-todres/try/1
|
|
~talsur-todres/try/1> :ls %
|
|
readme helo
|
|
~talsur-todres/try/1>
|
|
|
|
This is sort of like being in a detached HEAD in git.
|
|
|
|
3
|
|
|
|
Start a yacht
|
|
|
|
Each Urbit destroyer can delegate around four billion yachts. Yachts are
|
|
also urbit ships, but are pegged to their parent identity, and are set
|
|
up to mirror their filesystem. We can generate a `[ship: ticket]` pair
|
|
for a yacht by using the `:ticket` utility:
|
|
|
|
~talsur-todres/try=> :ticket ~talsur-todres-talsur-todres
|
|
~talsur-todres-talsur-todres: ~figpem-fapmyl-wacsud-racwyd
|
|
|
|
Every yacht for a particular destroyer ends in the same `ship-name`, and
|
|
has every possible destroyer prefix. For example,
|
|
`~tasfyn-partyv-talsur-todres` is also a valid yacht from
|
|
`~talsur-todres`.
|
|
|
|
Start up a new `vere` process with something like `bin/vere -c yacht`.
|
|
Then run `:begin` and enter the `[ship: ticket]` pair you just generated
|
|
when prompted. When the process is complete you should get a
|
|
`; ~talsur-todres-talsur-todres :y1: is your neighbor` message on your
|
|
destroyer. To confirm that everything is working properly, you can use
|
|
`:hi` to send a message:
|
|
|
|
~talsur-todres/try=> :hi ~talsur-todres-talsur-todres "whats up"
|
|
hi ~talsur-todres-talsur-todres successful
|
|
~talsur-todres/try=>
|
|
|
|
Which will appear on your new yacht:
|
|
|
|
< ~talsur-todres: whats up
|
|
~talsur-todres-talsur-todres/try=>
|
|
|
|
You should also see the contents of your `/try` desk mirrored on your
|
|
yacht:
|
|
|
|
~talsur-todres-talsur-todres/try=> :ls %
|
|
readme helo
|
|
~talsur-todres-talsur-todres/try=>
|
|
|
|
Making another change on your destroyer should automatically propagate
|
|
down to your yacht:
|
|
|
|
~talsur-todres/try=> :into %/helo/txt 'back to mars'
|
|
written
|
|
~talsur-todres/try=>
|
|
|
|
[%merge-fine ~talsur-todres %try]
|
|
~talsur-todres-talsur-todres/try=> :cat %/helo/txt
|
|
back to mars
|
|
~talsur-todres-talsur-todres/try=>
|
|
|
|
4
|
|
|
|
Move files around
|
|
|
|
Another familiar command line utility is `:mv`:
|
|
|
|
~talsur-todres/try=> :mv %/helo/txt %/test/helo/txt
|
|
moved
|
|
~talsur-todres/try=>
|
|
|
|
[%merge-fine ~talsur-todres %try]
|
|
~talsur-todres-talsur-todres/try=> :cat %/test/helo/txt
|
|
back to mars
|
|
~talsur-todres-talsur-todres/try=>
|
|
|
|
In `%clay` we don't use file extensions or folders. A path either does
|
|
or does not have anything in it. There's no need to do the equivalent of
|
|
`mkdir` before moving something.
|
|
|
|
We also implement the familiar `:rm`:
|
|
|
|
~talsur-todres/try=> :rm %/test/helo/txt
|
|
removed
|
|
~talsur-todres/try=> :cat %/test/helo/txt
|
|
file /~talsur-todres/try/~2014.11.26..16.49.52..3f5e/test/helo/txt not available
|
|
~talsur-todres/try=>
|
|
|
|
[%merge-fine ~talsur-todres %try]
|
|
~talsur-todres-talsur-todres/try=> :cat %/test/helo/txt
|
|
file /~tasfyn-partyv-talsur-todres/try/~2014.11.26..16.50.15..556b/test/helo/txt not available
|
|
~talsur-todres-talsur-todres/try=>
|