@@ -0,0 +1,356 @@
1+---
2+navhome: /docs
3+sort: 8
4+title: From Unix
5+---
6+
7+<div class="row">
8+<div class="col-md-8">
9+
10+# Using Urbit from Unix
11+
12+With `urb` at your Unix command line, you can execute hoon, run
13+dojo commands, and more. Additionally, with `fuse`, you can
14+inspect the urbit namespace.
15+
16+</div>
17+</div>
18+
19+## Installation
20+
21+These commands are in the a [separate
22+repo](https://github.com/urbit/urb). Clone this repo to get the
23+commands.
24+
25+You'll also need the `requests` and `fuse` libraries for python.
26+If you have `pip`, you can just run:
27+
28+```
29+pip install requests fuse-python
30+```
31+
32+Otherwise, on Ubuntu, run:
33+
34+```
35+apt-get install python-requests python-fuse
36+```
37+
38+Then you can either run the python commands from the git repo, or
39+put them somewhere in your path.
40+
41+## `urb`
42+
43+`urb` transfers data from a source to a sink. Examples of data
44+sources include literal data, a file, a URL, or some
45+tranformation of another source. Examples of data sinks are
46+stdout, output file, POST request, or dojo command.
47+
48+Here are some examples. This takes the literal data "hello
49+world" and sends it to stdout (the default sink).
50+
51+ urb --data 'hello world'
52+
53+Let's run some hoon code at the dojo.
54+
55+ urb --dojo '(add 2 2)'
56+
57+Let's convert a markdown file to html.
58+
59+ urb --data @@file.md -m md -m html
60+
61+Mount the `%home` desk. This syncs the `home` desk into the pier
62+directory.
63+
64+ urb --dojo '+hood/mount /=home=' --app hood
65+
66+### Sources
67+
68+Sources can be any of the following:
69+
70+- `-d, --dojo command` runs a dojo command. This is commonly
71+ naked hoon code, but it can also be a generator, or any of the
72+ other ways the dojo gets data.
73+
74+- `-D, --data text` is literal text data, as a cord.
75+
76+- `-c, --clay path` pulls data from Urbit's filesystem.
77+
78+- `-u, --url url` pulls data from a URL.
79+
80+- `-m, --mark mark source` converts the output from another source to
81+ a new 'mark' (datatype).
82+
83+- `-H, --hoon code source` transforms the output of another
84+ source by running it through some hoon code.
85+
86+- `[source-0 source-1 ...]`. Sources can be combined into tuples
87+ of different sources.
88+
89+Any of the arguments to a source (except in the "compound
90+sources" `--mark` and `--hoon`) can be replaced by `-` to
91+represent stdin or `@@filename` to pull data in from a Unix file.
92+Thus, `urb [-D @@file1 -D - -D @@file2]` is equivalent to Unix's
93+`cat file1 - file2`.
94+
95+Additionally, if no source is specified, `--data -` (stdin as
96+literal text data) is assumed.
97+
98+### Sinks
99+
100+- `-s, --stdout` outputs to stdout. This is the default.
101+
102+- `-f, --output-file path` writes to a unix file.
103+
104+- `-C, --output-clay path` writes to Urbit's filesystem.
105+
106+- `-U, --output-url url` sends a POST request with the data to
107+ the URL.
108+
109+- `-p, --app app` sends the data to an urbit app.
110+
111+- `-x, --command` outputs to a literal dojo command.
112+
113+## `fuse`
114+
115+Urbit's namespace is accessible through the `fuse` command.
116+`fuse` takes all the normal FUSE arguments, which you can see
117+with `fuse -h`. Generally, you just run `fuse MOUNT-POINT`.
118+
119+When accessing the namespace through `fuse`, everything is
120+read-only. If you want to write to Clay, mount a desk, as
121+described above.
122+
123+Let's look first in the Clay portion of the Urbit namespace.
124+Assume we've mounted to `./pt`.
125+
126+ $ ls ./pt/c/=/=/=
127+ app arvo gen lib mar ren sec sur web
128+ $ ls ./pt/c/=/=/=/arvo
129+ ames behn clay dill eyre ford gall hoon zuse
130+
131+Those `=`s aren't decorative. The first `=` means "current
132+ship", the second "current desk", and the third "current
133+revision". Let's try something a little more exciting.
134+
135+This runs the Unix `diff` command on the first and current
136+versions of the `app/gh/hoon` file, showing all the changes we've
137+made to the file.
138+
139+```
140+$ diff pt/c/=/=/{1,=}/app/gh/hoon
141+73c73,75
142+< (malt (turn issues |=(issue:gh [(rsh 3 2 (scot %ui number)) ~])))
143+---
144+> %- malt ^- (list {@ta $~})
145+> :- [%gh-list-issues ~]
146+> (turn issues |=(issue:gh [(rsh 3 2 (scot %ui number)) ~]))
147+92c94,101
148+< read-y=(read-get /issues)
149+---
150+> read-y=(read-static %gh-list-issues ~)
151+> sigh-x=sigh-list-issues-x
152+> sigh-y=sigh-list-issues-y
153+> ==
154+> ^- place :: /issues/mine/<mark>
155+> :* guard={$issues $mine @t $~}
156+> read-x=read-null
157+> read-y=|=(pax/path [ost %diff %arch `0vsen.tinel ~])
158+126c135
159+< ^- place :: /issues/by-repo/<user>/<repo>
160+---
161+> ^- place :: /issues/by-repo/<user>/<repo>/<number>
162+131c140,146
163+< read-y=(read-static ~)
164+---
165+> ^= read-y
166+> |= pax/path
167+> %. pax
168+> ?: ((sane %tas) -.+>+>.pax)
169+> (read-static ~)
170+> (read-static %gh-issue ~)
171+> ::
172+137a153,159
173+> sigh-y=sigh-strange
174+> ==
175+> ^- place :: /issues/by-repo/<u>/<r>/<n>/<mark>
176+> :* guard={$issues $by-repo @t @t @t @t $~}
177+> read-x=read-null
178+> read-y=|=(pax/path [ost %diff %arch `0vsen.tinel ~])
179+> sigh-x=sigh-strange
180+```
181+
182+Urbit's namespace is not just revisioned, but global. Here's a
183+diff of our version of `arvo/gall/hoon` compared to the one on
184+the `~bud` urbit.
185+
186+```
187+$ diff pt/c/{~bud,=}/=/=/arvo/gall/hoon
188+2d1
189+<
190+640a640,644
191+> =+ ?. ?=($x ren)
192+> [mar=%$ tyl=tyl]
193+> =+ `path`(flop tyl)
194+> ?> ?=(^ -)
195+> [mar=i tyl=(flop t)]
196+643c647
197+< ((slog leaf+"peek find fail" >tyl< ~) [~ ~])
198+---
199+> ((slog leaf+"peek find fail" >tyl< >mar< ~) [~ ~])
200+654a659,660
201+> ?. =(mar p.q.caz)
202+> [~ ~]
203+1308a1315,1316
204+> ?. ?=(^ tyl)
205+> ~
206+```
207+
208+Besides Clay, the namespace contains Gall apps. One common usage
209+of the app namespace is to expose APIs. For example, if you
210+start the `%gh` app (`|start %gh`), you can do things like `cat`
211+an issue from a repository.
212+
213+```
214+$ cat pt/g/=/gh/=/issues/by-repo/philipcmonktest/testing/7/txt
215+title: big news! (#7)
216+state: open
217+creator: philipcmonktest
218+created-at: 2016-03-24T22:27:33Z
219+assignee: philipcmonktest
220+labels: invalid, wontfix, help wanted
221+comments: 0
222+url: https://api.github.com/repos/philipcmonktest/testing/issues/7
223+
224+Yup, that's it. i mean, maybe it's a bit longer than that.
225+
226+But you get the point, right?
227+
228+Code `is` cool!
229+```
230+
231+Or all open issues for a repository.
232+
233+```
234+$ cat pt/g/=/gh/=/issues/by-repo/philipcmonktest/testing/txt
235+title: i found a bug! (#11)
236+state: open
237+creator: philipcmonktest
238+created-at: 2016-04-14T23:14:49Z
239+assignee: none
240+labels:
241+comments: 1
242+url: https://api.github.com/repos/philipcmonktest/testing/issues/11
243+
244+
245+----------------------------------------
246+title: more newz (#8)
247+state: open
248+creator: philipcmonktest
249+created-at: 2016-03-24T22:29:16Z
250+assignee: none
251+labels:
252+comments: 4
253+url: https://api.github.com/repos/philipcmonktest/testing/issues/8
254+
255+Yup, that's it. i mean, maybe it's a bit longer than that.
256+
257+But you get the point, right?
258+
259+Code `is` cool!
260+----------------------------------------
261+title: big news! (#7)
262+state: open
263+creator: philipcmonktest
264+created-at: 2016-03-24T22:27:33Z
265+assignee: philipcmonktest
266+labels: invalid, wontfix, help wanted
267+comments: 0
268+url: https://api.github.com/repos/philipcmonktest/testing/issues/7
269+
270+Yup, that's it. i mean, maybe it's a bit longer than that.
271+
272+But you get the point, right?
273+
274+Code `is` cool!
275+----------------------------------------
276+title: something different (#4)
277+state: open
278+creator: philipcmonktest
279+created-at: 2016-01-26T21:45:08Z
280+assignee: philipcmonktest
281+labels: duplicate, help wanted, question, bug
282+comments: 1
283+url: https://api.github.com/repos/philipcmonktest/testing/issues/4
284+```
285+
286+Don't like the textual format? How about we get the raw JSON
287+(and prettyprint it).
288+
289+```
290+$ cat pt/g/=/gh/=/issues/by-repo/philipcmonktest/testing/7/json | python -m json.tool
291+{
292+ "assignee": {
293+ "avatar_url": "https://avatars.githubusercontent.com/u/16787461?v=3",
294+ "events_url": "https://api.github.com/users/philipcmonktest/events{/privacy}",
295+ "followers_url": "https://api.github.com/users/philipcmonktest/followers",
296+ "following_url": "https://api.github.com/users/philipcmonktest/following{/other_user}",
297+ "gists_url": "https://api.github.com/users/philipcmonktest/gists{/gist_id}",
298+ "gravatar_id": "",
299+ "html_url": "https://github.com/philipcmonktest",
300+ "id": 16787461,
301+ "login": "philipcmonktest",
302+ "organizations_url": "https://api.github.com/users/philipcmonktest/orgs",
303+ "received_events_url": "https://api.github.com/users/philipcmonktest/received_events",
304+ "repos_url": "https://api.github.com/users/philipcmonktest/repos",
305+ "site_admin": false,
306+ "starred_url": "https://api.github.com/users/philipcmonktest/starred{/owner}{/repo}",
307+ "subscriptions_url": "https://api.github.com/users/philipcmonktest/subscriptions",
308+ "type": "User",
309+ "url": "https://api.github.com/users/philipcmonktest"
310+ },
311+ "body": "Yup, that's it. i mean, maybe it's a bit longer than that.\r\n\r\nBut you get the point, right?\r\n\r\nCode `is` cool!",
312+ "closed_at": null,
313+ "closed_by": null,
314+ "comments": 0,
315+ "comments_url": "https://api.github.com/repos/philipcmonktest/testing/issues/7/comments",
316+ "created_at": "2016-03-24T22:27:33Z",
317+ "events_url": "https://api.github.com/repos/philipcmonktest/testing/issues/7/events",
318+ "html_url": "https://github.com/philipcmonktest/testing/issues/7",
319+ "id": 143377108,
320+ "labels": [
321+ {
322+ "color": "ffffff",
323+ "name": "wontfix",
324+ "url": "https://api.github.com/repos/philipcmonktest/testing/labels/wontfix"
325+ }
326+ ],
327+ "labels_url": "https://api.github.com/repos/philipcmonktest/testing/issues/7/labels{/name}",
328+ "locked": false,
329+ "milestone": null,
330+ "number": 7,
331+ "repository_url": "https://api.github.com/repos/philipcmonktest/testing",
332+ "state": "open",
333+ "title": "big news!",
334+ "updated_at": "2016-03-24T22:27:33Z",
335+ "url": "https://api.github.com/repos/philipcmonktest/testing/issues/7",
336+ "user": {
337+ "avatar_url": "https://avatars.githubusercontent.com/u/16787461?v=3",
338+ "events_url": "https://api.github.com/users/philipcmonktest/events{/privacy}",
339+ "followers_url": "https://api.github.com/users/philipcmonktest/followers",
340+ "following_url": "https://api.github.com/users/philipcmonktest/following{/other_user}",
341+ "gists_url": "https://api.github.com/users/philipcmonktest/gists{/gist_id}",
342+ "gravatar_id": "",
343+ "html_url": "https://github.com/philipcmonktest",
344+ "id": 16787461,
345+ "login": "philipcmonktest",
346+ "organizations_url": "https://api.github.com/users/philipcmonktest/orgs",
347+ "received_events_url": "https://api.github.com/users/philipcmonktest/received_events",
348+ "repos_url": "https://api.github.com/users/philipcmonktest/repos",
349+ "site_admin": false,
350+ "starred_url": "https://api.github.com/users/philipcmonktest/starred{/owner}{/repo}",
351+ "subscriptions_url": "https://api.github.com/users/philipcmonktest/subscriptions",
352+ "type": "User",
353+ "url": "https://api.github.com/users/philipcmonktest"
354+ }
355+}
356+```