content/docs/userspace/dist/tools.md · urbit.org

git.iko.soy/urbit.org

on 514b5fc help sign in

urbit.org/content/docs/userspace/dist/tools.md

342 lines 7.5 kB history raw

1+++

2title = "Dojo Tools"

3weight = 5

4template = "doc.html"

5+++

7A number of generators are included for managing and viewing the status of desks and their agents. Each of these are documented below.

9Note that some old generators have been replaced:

11- `|start` - Replaced with [`|rein`](#rein).

13- `|fade` - Replaced with [`|nuke`](#nuke).

14- `|doze` - Replaced with [`|rein`](#rein) or [`|suspend`](#suspend).

15- `|wake` - Replaced with [`|rein`](#rein) or [`|revive`](#revive).

16- `+trouble` - This still exists but is deprecated, and is now an alias for [`+vats`](#vats).

18---

20## `+vats`

22Print out the status of each installed desk.

24Desks in Clay which aren't installed will be omitted.

26Fields:

28- `/sys/kelvin` - The version of `%zuse` the desk is compatible with.

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

30- `%cz hash` - The hash of the desk.

31- `app status` - May be `suspended` or `running`.

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

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

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

35- `updates` - May be `local`, `tracking` or `paused`. Local means it will receive updates via commits on the local ship. Tracking means it will receive updates from the `source ship`. Paused means it will not receive updates.

36- `source desk` - The desk on the `source ship`.

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

38- `pending updates` - Updates waiting to be applied due to incompatibility.

40#### Arguments

42None.

44#### Examples

46```

47> +vats

48%base

49 /sys/kelvin: [%zuse 420]

50 base hash: ~

51 %cz hash: 0v6.2nqmu.oqm24.ighl6.n0gp9.s8res.feql1.dl8ap.isli3.jk0hu.acrd2

52 app status: running

53 force on: ~

54 force off: ~

55 publishing ship: ~

56 updates: tracking

57 source ship: ~zod

58 source desk: %base

59 source aeon: 3

60 pending updates: ~

61::

62%garden

63 /sys/kelvin: [%zuse 420]

64 base hash: ~

65 %cz hash: 0v1e.2h7hs.elq3g.1sdt7.qfga6.ganga.7p95j.aog44.8p5fe.kpr6v.7ai82

66 app status: running

67 force on: ~

68 force off: ~

69 publishing ship: ~

70 updates: tracking

71 source ship: ~zod

72 source desk: %garden

73 source aeon: 3

74 pending updates: ~

75```

77---

79## `+agents`

81Print out the status of Gall agents on a desk.

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

85#### Arguments

87```

88desk

89```

91#### Example

93```

94> +agents %garden

95status: running %hark-system-hook

96status: running %treaty

97status: running %docket

98status: running %settings-store

99status: running %hark-store

100```

101

102---

103

104## `|suspend`

105

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

107

108The 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.

109

110#### Arguments

111

112```

113desk

114```

115

116#### Examples

117

118```

119|suspend %bitcoin

120```

121

122---

123

124## `|revive`

125

126Revive all agents on a desk, migrating archived states.

127

128All 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.

129

130#### Arguments

131

132```

133desk

134```

135

136#### Examples

137

138```

139|revive %bitcoin

140```

141

142---

143

144## `|install`

145

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

147

148If 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.

149

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

151

152#### Arguments

153

154```

155ship desk, =local desk

156```

157

158#### Examples

159

160```

161|install ~zod %bitcoin

162```

163

164```

165|install our %webterm

166```

167

168```

169|install ~zod %bitcoin, =local %foo

170```

171

172---

173

174## `|uninstall`

175

176Uninstall a desk, suspending its agents and ignoring updates.

177

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

179

180Note 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.

181

182#### Arguments

183

184```

185desk

186```

187

188#### Examples

189

190```

191|uninstall %bitcoin

192```

193

194---

195

196## `|pause`

197

198Pause updates on a desk.

199

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

201

202#### Arguments

203

204```

205desk

206```

207

208#### Examples

209

210```

211|pause %bitcoin

212```

213

214---

215

216## `|resume`

217

218Resume updates on a desk.

219

220Start tracking previously [`|pause`](#pause)d updates from a desk's upstream source.

221

222#### Arguments

223

224```

225desk

226```

227

228#### Examples

229

230```

231|resume %bitcoin

232```

233

234---

235

236## `|nuke`

237

238Shut down an agent and permanently delete its state.

239

240The 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.

241

242#### Arguments

243

244```

245@tas, =desk ?

246```

247

248#### Examples

249

250Nuke a single agent:

251

252```

253|nuke %btc-wallet

254```

255

256Nuke every agent on a desk:

257

258```

259|nuke %bitcoin, =desk &

260```

261

262---

263

264## `|bump`

265

266Try to apply a kernel update.

267

268If `%zuse`'s kelvin version has decreased, try to apply the update. If any desks are incompatible with the new `%zuse` version, the update will fail. The update can be forced with the optional `force` argument, in which case incompatible desks will be `|suspend`ed. The `set` of desks to omit (and therefore suspend) can also be explicitly specified with the optional `except` argument.

269

270#### Arguments

271

272All optional:

273

274```

275, =force ?, =except (set desk)

276```

277

278#### Examples

279

280Try to apply update, failing if blocked by any desks:

281

282```

283|bump

284```

285

286Force the update, suspending incompatible desks:

287

288```

289|bump, =force &

290```

291

292Apply kernel update, omitting and suspending the specified desks:

293

294```

295|bump, =except (silt ~[%bitcoin %webterm])

296```

297

298---

299

300## `|rein`

301

302Adjust the state of a desk.

303

304This 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.

305

306#### Arguments

307

308```

309desk (list [? dude:gall]), =liv ?

310```

311

312#### Examples

313

314Start an agent:

315

316```