You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+54-13
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,10 @@
1
1
# azimuth-cli
2
-
The azimuth-cli is "Bridge for the command line." It should allow ship owners and operators to do the same things that they can in [Bridge](https://bridge.urbit.org/) but via the command line, and in batch mode.
3
2
4
-
The primary usage of the cli is to query and modify the [azimuth contracts](https://github.com/urbit/azimuth) on Ethereum.
3
+
This is a command line tool to work with Urbit ID, which is the idenity layer behind [Urbit](https://urbit.org/) and is managed as a set of NFTs on the Ethereum blockchain.
4
+
5
+
The azimuth-cli is "Bridge for the command line." It should allow Urbit ship owners and operators to do the same things that they can in [Bridge](https://bridge.urbit.org/) but via the command line, and in batch mode.
6
+
7
+
The primary functionality of the cli is to query and modify the [azimuth contracts](https://github.com/urbit/azimuth) on Ethereum.
5
8
6
9
## Install
7
10
@@ -12,6 +15,8 @@ Due to an issues when building the azimuth-js package (as described [here](https
12
15
Simply install the npm package globally:
13
16
`npm install -g azimuth-cli`
14
17
18
+
**When Upgrading to the L2 version:** Make sure to delete the `cli-config.json` file in your home directory, usually in a folder called `.azimuth/`.
19
+
15
20
### Development or Manual Install
16
21
1) Clone this [repo](https://github.com/lukebuehler/azimuth-cli)
17
22
1) run `npm install`
@@ -24,11 +29,19 @@ To run the tests:
24
29
25
30
26
31
## Usage
32
+
33
+
*Note: Using the CLI with a L2 roller is WIP, see [here for instructions](docs/roller.md).*
34
+
27
35
After installing the npm package, just type `azimuth-cli` in the command line to see the options. You can also use `azi` for short.
28
36
29
-
There are three main types of commands: `list`, `generate`, and `modify`. First, the `list` commands do not make any changes, they just print information to the command line. But `generate` commands usually save something to the current work directory; use this, for example, to generate HD wallets. The `modify` commands actually change the blockchain and usually require the private key of the address that owns the urbit point you are making a change to. The `modify` commands also save data to the work directory, such as Ethereum transaction receipts.
37
+
There are three main types of commands: `get`, `generate`, and `modify`. First, the `get` commands do not make any changes, they just print information to the command line. But `generate` commands usually save something to the current work directory; use this, for example, to generate HD wallets.
38
+
39
+
The `modify` commands actually change the blockchain and usually require the private key of the address that owns the urbit point you are making a change to. The `modify` commands have two versions: `modify-l1` and `modify-l2`. This is because Urbit IDs can either be modified directly through an Ethereum smart contract called Azimuth, aka "L1", or via a Layer 2 solution that is cheaper, which uses a "roller" that gathers transactions that modify Urbit IDs and then submits them as one batch to Ethereum, and is called the "L2" solution. The `modify` commands also save data to the work directory, such as Ethereum or roller transaction receipts.
30
40
31
-
More complicated operations--such as spawning ships, keying them, and transfering them to master tickets--cannot be executed in a single command. Multiple commands need to be called in order (see the example below).
41
+
More complicated operations--such as spawning ships, keying them, and transfering them to master tickets--cannot be executed in a single command. Multiple commands need to be called in order (see the examples below).
42
+
43
+
### Setting Up Your Own Layer 2 Roller
44
+
If you want to modify large batches of points in one go--for example spawn 200 planets--then you need to [run your own roller](docs/roller.md). By default, the CLI points to the official roller run by Urbit. See the `--roller-provider` option in the CLI.
32
45
33
46
### Work Directory & Idempotent Commands
34
47
Many commands, especially the `generate` and `modify` ones, need a work directory to fulfill their function. The reason for this is that a command may be called multiple times, but the end effect needs to always be the same. For example, if you call `azi generate spawn-list --count=10` multiple times, the resulting `spawn-list.txt` file will only be created once, and will not change in subsequent calls (unless the `--force` option is provided). The same goes for the `modify` commands.
@@ -42,35 +55,43 @@ The work directory is the current folder or can be supplied with the `--work-dir
42
55
For the full documentation, please install the cli and explore the commands and sub-commands with the `--help` option.
43
56
44
57
`aimuth-cli`
45
-
*`list` - Prints azimuth data to the console.
58
+
*`get` - Retrieves data about points, rollers, and azimuth, and prints it to the console. By default, uses a L2 roller to get the information.
46
59
*`children <point>` - Lists all child points of a certain Urbit point.
47
60
*`owner <address>` - Lists all points owned by that Ethereum address.
48
61
*`details <point>` - Prints details about the point.
49
-
*`gas-price` - Outputs the current Etherum gas prices. This is helpful if you want to provide a gas limit in the `modify` commands.
62
+
*`gas-price` - Outputs the current Etherum gas prices. This is helpful if you want to provide a gas limit in the `modify-l1` commands.
63
+
*`roller-info` - Prints details about the L2 roller.
64
+
*`roller-info` - Prints pending roller transactions.
50
65
*`generate` - Generates various files that can be used in the `modify` commands.
51
66
*`spawn-list <point>` - Creates a `spawn-list.txt` file that contains a number of points that can be spawned under the provided point.
52
67
*`wallet` - Generates an HD wallet for each provided point and saves each wallet in JSON format in the current work directory. Use this especially if you plan to give the points away. Then, in subsequent commands, supply the `--use-wallet-files` option.
53
68
*`network-keys` - Creates the network keyfile for each supplied point, and either creates a JSON file with the private and public network keys or uses the network keys from the walled files.
54
69
*`report` - Generates a CSV report for the provided points, containing patp, p, ticket, network keys, addresses, and transactions executed so far.
55
-
*`modify` - Modifies the state of one or more points on the Ethereum blockchain (the azimuth contracts). For many of these commands to work, other files will have to have been generated with the `generate` commands.
70
+
*`modify-l1` - Modifies the state of one or more points on the Ethereum blockchain (the azimuth contracts). For many of these commands to work, other files will have to have been generated with the `generate` commands.
56
71
*`spawn` - Spawns multiple points to the supplied address
57
72
*`management-proxy` - Sets the management proxy address for the points.
58
73
*`spawn-proxy` - Sets the spawn-proxy address for the points.
59
74
*`network-key` - Sets the network keys for the points, which is required to be able to boot the Urbit.
60
75
*`transfer` - Transfers the point to a target address or the wallet files.
61
-
76
+
*`modify-l2` - Modifies the state of one or more points via a L2 roller. The roller then submits the changes to the L2 Ethereum contract. Any point modified via this command, needs to be on L2.
77
+
*`spawn` - Spawns multiple points to the supplied address. The galaxy or star that spawns needs to be on L2 or the spawn proxy needs to be on L2.
78
+
*`management-proxy` - Sets the management proxy address for the points.
79
+
*`network-key` - Sets the network keys for the points, which is required to be able to boot the Urbit.
80
+
*`transfer` - Transfers the point to a target address or the wallet files.
62
81
63
82
### Examples
64
-
#### Spawn, Set Network Keys, and Transfer to Master Ticket
83
+
#### Spawn, Set Network Keys, and Transfer to Master Ticket on Azimuth (L1)
65
84
This is an example of spawning planets and creating a master ticket for them. You would do this if you want to give some planets away to friends. It is similar to what you can do in Bridge, but we do it for 5 planets in one go. Generating a master ticket itself is not enough, though. Ownership needs to be transferred to the owner address that is associated with the master ticket. But for the master ticket to be usable, networking keys need to be set. Hence, we first spawn to a temporary address (usually the same as the owner or spawn-proxy of the star, here ~sardys), then set the keys, and only then move the planet to its own address--that of the HD wallet.
66
85
86
+
The star you are spawning from needs to be on L1!
87
+
67
88
```
68
89
# create a directory for your work
69
90
mkdir spawn-planets
70
91
cd spawn-planets
71
92
72
93
# pick 5 random, unspawned planets under ~sardys and save them in a file
73
-
azi generate spawn-list ~sardys --count=5 --pick=random
94
+
azi generate spawn-list ~sardys --count=5 --pick=random --use-azimuth
74
95
75
96
# now, generate HD wallet files based on the previous list
76
97
azi generate wallet --points-file=spawn-list.txt
@@ -82,15 +103,35 @@ azi generate network-key --use-wallet-files
82
103
83
104
# spawn the 5 planets that can be found in the wallet files,
84
105
# providing the PK of the wallet that owns ~sardys, or is the spawn proxy
85
-
azi modify spawn --use-wallet-files --address=0xSardysOwnershipAddress --private-key=0x1234567890
106
+
azi modify-l1 spawn --use-wallet-files --address=0xSardysOwnershipAddress --private-key=0x1234567890
86
107
87
108
# set the network keys on the blockchain
88
-
azi modify network-key --use-wallet-files --private-key=0x1234567890
109
+
azi modify-l1 network-key --use-wallet-files --private-key=0x1234567890
89
110
90
111
# transfer each planet ownership to the address of the wallet
91
-
azi modify transfer --use-wallet-files --private-key=0x1234567890
112
+
azi modify-l1 transfer --use-wallet-files --private-key=0x1234567890
92
113
```
93
114
115
+
#### Spawn, Set Network Keys, and Transfer to Master Ticket on Azimuth (L2)
94
116
117
+
This is the same example as above but using a roller to spawn the planets.
118
+
119
+
The star you are spawning from needs to be on L2 or have the spawn proxy set to L2! Here is more info about the [Layer 2 solution](https://urbit.org/docs/azimuth/l2/layer2).
120
+
121
+
```
122
+
azi generate spawn-list ~sampel --count=2 --pick=random --use-roller
123
+
124
+
azi generate wallet --points-file=spawn-list.txt
125
+
126
+
azi generate network-key --use-wallet-files
127
+
128
+
azi modify-l2 spawn --use-wallet-files --address=0xSpawnProxy --private-key=0xSpawnProxyKey
129
+
130
+
azi modify-l2 management-proxy --use-wallet-files --address=0xManagementProxy --private-key=0xSpawnProxyKey
131
+
132
+
azi modify-l2 network-key --use-wallet-files --private-key=0xSpawnProxyKey
133
+
134
+
azi modify-l2 transfer --use-wallet-files --private-key=0xSpawnProxyKey
0 commit comments