49 releases (32 breaking)
new 0.38.2 | Sep 30, 2024 |
---|---|
0.37.0 | Jul 23, 2024 |
0.34.0 | Mar 18, 2024 |
0.31.0 | Nov 27, 2023 |
0.3.0 | Jul 12, 2021 |
#267 in Magic Beans
737 downloads per month
530KB
11K
SLoC
icx
A command line tool to use the ic-agent
crate directly. It allows simple communication with
the Internet Computer.
Installing icx
To install icx
you will have to build it locally, using cargo
. Make a clone of this repository,
then in it simply run cargo build
:
git clone https://github.com/dfinity/agent-rust.git
cd agent-rust
cargo build
The output executable will be in target/debug/icx
.
Using icx
To get help, simply use icx --help
.
Identity
To read a PEM file, you can pass it with the --pem
argument. The PEM file must be a valid
key that can be used for the Internet Computer signing and validation.
Root Key
For non-IC networks, pass --fetch-root-key
to fetch the root key. When this argument is not present,
icx uses the hard-coded public key.
Examples
To call the management canister's create_canister
function, you can use the following:
icx update aaaaa-aa create_canister
If you have a candid file, you can use it to validate arguments. Pass it in with the
--candid=path/to/the/file.did
argument:
icx query 75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q greet --candid=~/path/greet.did '("World")'
Sign and Send Separation
Pass --serialize
when use icx update
and icx query
will serialize the signed canister call message as json.
The output will print to stdout. When use icx update
, a corresponding request_status message is also generated and printed to stderr.
In the default IC project generated with dfx new
and the local emulator has started with dfx start --background
.
Sign
icx --fetch-root-key update --serialize rwlgt-iiaaa-aaaaa-aaaaa-cai greet '("everyone")' > output.txt
head -n 1 output.txt > update.json
tail -n 1 output.txt > request_status.json
rwlgt-iiaaa-aaaaa-aaaaa-cai
is the ID of hello canister in the default project.
Send
cat update.json | icx send
...
RequestID: 0x1234....
Request status
cat request_status.json | icx --fetch-root-key send
...
("Hello, everyone!")
When sending message to the IC main net, all --fech-root-key
are not required. So the sign step can be executed on an air-gapped machine.
Dependencies
~28–42MB
~766K SLoC