dfx canister
Use the dfx canister command with options and subcommands to manage canister operations and interaction with the ICP mainnet or the local development environment. In most cases, you use dfx canister subcommands to manage the canister lifecycle and to perform key tasks such as calling program functions.
The basic syntax for running dfx canister commands is:
dfx canister <subcommand> [options]
Depending on the dfx canister subcommand you specify, additional arguments and options might apply or be
required. To view usage information for a specific dfx canister subcommand, specify the subcommand and the --help
flag. For example, to see usage information for dfx canister call, you can run the following command:
dfx canister call --help
For reference information and examples that illustrate using dfx canister commands, select an appropriate command.
| Command | Description |
|---|---|
call | Calls a specified method on a deployed canister. |
create | Creates an empty canister and assigns a canister ID to the canister name. |
delete | Deletes a currently stopped canister. |
deposit-cycles | Deposit cycles into the specified canister. |
help | Displays usage information message for a specified subcommand. |
id | Displays the identifier of a canister. |
info | Get the hash of a canister’s Wasm module and its current controller. |
install | Installs compiled code in a canister. |
logs | Returns the logs from a canister. |
metadata | Displays metadata of a canister. |
request-status | Requests the status of a call to a canister. |
send | Send a previously-signed message. |
set-id | Sets the identifier of a canister. |
sign | Sign a canister call and generate a message file. |
start | Starts a stopped canister. |
status | Returns the current status of a canister as defined. |
stop | Stops a currently running canister. |
uninstall-code | Uninstalls a canister, removing its code and state. Does not delete the canister. |
update-settings | Update one or more of a canister's settings (i.e its controller, compute allocation, or memory allocation.). |
url | Displays the URL of a canister. |
Overriding the default deployment environment
By default, dfx canister commands run on the local development environment specified in the dfx.json file. If
you want to send a dfx canister subcommand to the mainnet or the playground without changing the settings in
your dfx.json configuration file, you can explicitly specify the URL to connect to using the --network option.
For example, to register unique canister identifiers for a project on the local development environment, you can run the following command:
dfx canister create --all
If you want to register unique canister identifiers for the same project on the mainnet, you can run the following command:
dfx canister create --all --network ic
dfx comes with an alias of ic, which is configured to point to the mainnet. You can also pass a URL as a
network option, or you can configure additional aliases in dfx.json under the networks configuration, or
in $HOME/.config/dfx/networks.json.
To illustrate, you can call a canister and function running on a local custom network using a command similar to the following:
dfx canister call counter get --network http://192.168.3.1:5678
Performing a call through a cycles wallet
By default, most dfx canister commands to the mainnet are signed by and sent from your own principal.
Exceptions are commands that require cycles: dfx canister create and dfx canister deposit-cycles. These automatically go through the cycles wallet. Occasionally, you may want to make a call from the cycles wallet, e.g. when only the wallet is allowed to call a certain function. To send a call through the cycles wallet, you can use the --wallet option.
You will either specify the cycles wallet's principal, or the name of an identity associated with a cycles wallet.
Specifying a cycles wallet by principal
To specify a cycles wallet by principal, pass the principal directly.
dfx canister status <canister name> --wallet <wallet id>
As a concrete example, if you want to request the status of a canister on the mainnet that is only controlled by your wallet, you would run the following:
dfx identity get-wallet --network ic
This command outputs your wallet's principal (e.g. 22ayq-aiaaa-aaaai-qgmma-cai) on the ic network. Using this ID,
you can then query the status of the canister as follows:
dfx canister status --network ic --wallet 22ayq-aiaaa-aaaai-qgmma-cai
Specifying a cycles wallet by identity name
You can also specify the name of an identity, in which case dfx will look up the cycles wallet's principal.
For example, the following command will query the status of a canister, using the cycles wallet associated with the default identity on the mainnet:
dfx canister status --network ic --wallet default
As another example, the following commands are equivalent:
dfx canister status --network ic --wallet $(dfx identity get-wallet --network ic --identity alice)
dfx canister status --network ic --wallet alice
dfx canister call
Use the dfx canister call command to call a specified method on a deployed canister.
Basic usage
dfx canister call [options] <canister_name> <method_name> [argument]
Options
You can use the following options with the dfx canister call command.
| Option | Description |
|---|---|
--argument-file <argument-file> | Specifies the file from which to read the argument to pass to the method. Stdin may be referred to as -. |
--async | Specifies not to wait for the result of the call to be returned by polling the local development environment. Instead return a response ID. |
--candid <file.did> | Provide the .did file with which to decode the response. Overrides value from dfx.json for project canisters. |
--impersonate <principal> | Specifies a principal on behalf of which requests to a local PocketIC instance are sent. |
--output <output> | Specifies the output format to use when displaying a method’s return result. The valid values are idl, 'json', pp and raw. The pp option is equivalent to idl, but is pretty-printed. |
--query | Sends a query request instead of an update request. For information about the difference between query and update calls, see Canisters include both program and state. |
--random <random> | Specifies the config for generating random arguments. |
--type <type> | Specifies the data format for the argument when making the call using an argument. The valid values are idl and raw. |
--update | Sends an update request to a canister. This is the default if the method is not a query method. |
--with-cycles <amount> | Specifies the amount of cycles to send on the call. Deducted from the wallet. Requires --wallet as an option to dfx canister. |
Arguments
You can specify the following arguments for the dfx canister call command.
| Argument | Description |
|---|---|
canister_name | Specifies the name of the canister to call. The canister name is a required argument and should match the name you have configured for a canister in the canisters section of the dfx.json configuration file. |
method_name | Specifies the method name to call on the canister. The canister method is a required argument. |
argument | Specifies the argument to pass to the method. |
Specifies the argument to pass to the method
Depending on your program logic, the argument can be a required or optional argument. You can specify a data format type using the --type option if you pass an argument to the canister. By default, you can specify arguments using the Candid (idl) syntax for data values. You can use raw as the argument type if you want to pass raw bytes.
Examples
You can use the dfx canister call command to invoke specific methods, with or without arguments, after you have installed the canister's code using the dfx canister install command. For example, to invoke the get method for a canister with a canister_name of counter, you can run the following command:
dfx canister call counter get --async
In this example, the command includes the --async option to indicate that you want to make a separate request-status call rather than waiting to poll the local development environment or the mainnet for the result.
The --async option is useful when processing an operation might take some time to complete. The option enables you to continue performing other operations then check for the result using a separate dfx canister request-status command. The returned result will be displayed as the IDL textual format.
Using the IDL syntax
You can explicitly specify that you are passing arguments using the IDL syntax by running commands similar to the following for a Text data type:
dfx canister call hello greet --type idl '("Lisa")'
("Hello, Lisa!")
dfx canister call hello greet '("Lisa")' --type idl
("Hello, Lisa!")
You can also implicitly use the IDL by running a command similar to the following:
dfx canister call hello greet '("Lisa")'
("Hello, Lisa!")
To specify multiple arguments using the IDL syntax, use commas between the arguments. For example:
dfx canister call contacts insert '("Amy Lu","01 916-335-2042")'
dfx canister call hotel guestroom '("Deluxe Suite",42,true)'
You can pass raw data in bytes by running a command similar to the following:
dfx canister call hello greet --type raw '4449444c00017103e29883'
This example uses the raw data type to pass a hexadecimal to the greet function of the hello canister.
JSON output
The --output json option formats the output as JSON.
Candid types don't map 1:1 to JSON types. Notably, the following Candid types map to strings rather than numbers: nat, nat64, int, int64.
These are the mappings:
| Candid type | JSON type |
|---|---|
null | null |
bool | boolean |
nat | string |
nat8 | number |
nat16 | number |
nat32 | number |
nat64 | string |
int | string |
int8 | number |
int16 | number |
int32 | number |
int64 | string |
float32 | float or "NaN" |
float64 | float or "NaN" |
text | string |
opt | array with 0 or 1 elements |
vec | array |
record | object |
variant | object |
blob | array of numbers |
dfx canister create
Use the dfx canister create command to register one or more canister identifiers without compiled code. The new
canister principals are then recorded in canister_ids.json for non-local networks. You must be connected to the local
development or the mainnet to run this command.
Note that you can only run this command from within the project directory structure. For example, if your project name
is hello_world, your current working directory must be the hello_world top-level project directory or one of its
subdirectories.
Basic usage
dfx canister create [options] [--all | canister_name]
Options
You can use the following options with the dfx canister create command.
| Option | Description |
|---|---|
-c, --compute-allocation <allocation> | Specifies the canister's compute allocation. This should be a percent in the range [0..100]. |
--controller <principal> | Specifies the identity name or the principal of the new controller. |
--created-at-time <timestamp> | Transaction timestamp, in nanoseconds, for use in controlling transaction deduplication, default is system time. |
--from-subaccount <subaccount> | Subaccount of the selected identity to spend cycles from. |
--memory-allocation <memory> | Specifies how much memory the canister is allowed to use in total. This should be a value in the range [0..12 GiB]. A setting of 0 means the canister will have access to memory on a “best-effort” basis. It will only be charged for the memory it uses, but at any point in time may stop running if it tries to allocate more memory when there isn’t space available on the subnet. |
--reserved-cycles-limit <limit> | Specifies the upper limit for the canister's reserved cycles. |
--wasm-memory-limit <limit> | Specifies a soft upper limit for the canister's heap memory. |
--wasm-memory-threshold <threshold> | Specifies a threshold remaining amount of memory before the canister's low-memory hook runs. |
--log-viewer <principal> | Specifies the principal as an allowed viewer. Can be specified more than once. Cannot be used with --log-visibility. |
--log-visibility <visibility> | Specifies who can read the canister's logs: "controllers" or "public". For custom allowed viewers, use --log-viewer. |
--no-wallet | Performs the call with the user identity as the sender of messages. Bypasses the wallet canister. Enabled by default. |
--with-cycles <number-of-cycles> | Specifies the initial cycle balance to deposit into the newly created canister. The specified amount needs to take the canister create fee into account. This amount is deducted from the wallet's cycle balance. |
--specified-id <PRINCIPAL> | Attempts to create the canister with this canister ID. |
--subnet-type <subnet-type> | Specify the subnet type to create the canister on. If no subnet type is provided, the canister will be created on a random default application subnet. dfx ledger show-subnet-types can be used to list available subnet types. |
--subnet <subnet-principal> | Specify the subnet to create the canister on. If no subnet is provided, the canister will be created on a random default application subnet. |
--next-to <canister-principal> | Create canisters on the same subnet as the specified canister. |
Arguments
You can use the following argument with the dfx canister create command.
| Argument | Description |
|---|---|
--all | Enables you to create multiple canister identifiers at once if you have a project dfx.json file that defines multiple canisters. Note that you must specify --all or an individual canister name. |
canister_name | Specifies the name of the canister for which you want to register an identifier. If you are not using the --all option, the canister name is a required argument and must match at least one name that you have configured in the canisters section of the dfx.json configuration file for your project. |
Examples
For example, if you want to create the canister identifier for the project my_counter before writing the canister code, you can
run the following command:
dfx canister create my_counter
You can use the dfx canister create command with the --with-cycles option to specify the initial balance upon the
creation of one canister or all canisters in a project. For example, to specify an initial balance of 8000000000000
cycles for all canisters, run the following command:
dfx canister create --with-cycles 8000000000000 --all
Allocating message processing
The --compute-allocation option allows you to allocate computing resources as a percentage in the range of 0 to 100
to indicate how often your canister should be scheduled for execution.
For example, assume you run the following command:
dfx canister create --all --compute-allocation 50
With this setting, all of the canisters in the current project are assigned a 50% allocation. When canisters in the project receive ingress messages to process, the messages are scheduled for execution. Over 100 execution rounds, each canister’s messages will be scheduled for processing at least 50 times.
The default value for this option is 0—indicating that no specific allocation or scheduling is in effect. If all of your canisters use the default setting, processing occurs in a round-robin fashion.
dfx canister delete
Use the dfx canister delete command to delete a stopped canister from the local development environment or the mainnet. By default, this withdraws remaining cycles to your cycles wallet before deleting the canister.
Note that you can only run this command from within the project directory structure. For example, if your project name
is hello_world, your current working directory must be the hello_world top-level project directory or one of its
subdirectories.
Basic usage
dfx canister delete [options] [--all | canister_name]
Options
You can use the following options with the dfx canister delete command.
| Option | Description |
|---|---|
--no-withdrawal | Do not withdrawal cycles, just delete the canister. |
--initial-margin <cycles> | Leave this many cycles in the canister when withdrawing cycles. |
--to-subaccount | Subaccount of the selected identity to deposit cycles to. |
--withdraw-cycles-to-dank | Withdraw cycles to dank with the current principal. |
--withdraw-cycles-to-canister <principal> | Withdraw cycles from canister(s) to the specified canister/wallet before deleting. |
--withdraw-cycles-to-dank-principal <principal> | Withdraw cycles to dank with the given principal. |
-y, --yes | Auto-confirm deletion for a non-stopped canister |
Arguments
You can use the following arguments with the dfx canister delete command.
| Argument | Description |
|---|---|
--all | Deletes all of the canisters configured in the dfx.json file. Note that you must specify --all or an individual canister name. |
canister_name | Specifies the name of the canister you want to delete. Note that you must specify either a canister name or the --all option. |
Examples
To delete the hello_world canister, you can run the following command:
dfx canister delete hello_world
To delete all of the project's canisters you have deployed on the mainnet and configured in your dfx.json, you
can run the following command:
dfx canister delete --all --network=ic
dfx canister deposit-cycles
Use the dfx canister deposit-cycles command to deposit cycles from your configured wallet into a canister.
Note that you must have your cycles wallet configured for this to work.
Basic usage
dfx canister deposit-cycles <cycles> [--all | canister_name]
Arguments
You can use the following arguments with the dfx canister deposit-cycles command.
| Argument | Description |
|---|---|
--all | Deposits the specified amount of cycles into all canisters configured in dfx.json. Note that you must specify --all or an individual canister name. |
canister_name | Specifies the name of the canister you want to deposit cycles into. Note that you must specify either a canister name or the --all option. |
Options
You can use the following options with the dfx canister deposit-cycles command.
| Option | Description |
|---|---|
--created-at-time <timestamp> | Transaction timestamp, in nanoseconds, for use in controlling transaction deduplication, default is system time. |
--from-subaccount <subaccount> | Subaccount of the selected identity to spend cycles from. |
Examples
To add 1T cycles to the canister called hello, you can run the following command:
dfx canister deposit-cycles 1000000000000 hello
To add 2T cycles to each individual canister specified in dfx.json, you can run the following command:
dfx canister deposit-cycles 2000000000000 --all
dfx canister id
Use the dfx canister id command to output the canister identifier for a specific canister name.
Note that you can only run this command from within the project directory structure. For example, if your project name
is hello_world, your current working directory must be the hello_world top-level project directory or one of its
subdirectories.
If the canister has been deployed to the local development environment, the locally stored canister ID will be provided.
If a canister has been deployed by a third party, the user may set the .canisters[$CANISTER_NAME].remote[$NETWORK]
entry in dfx.json to the canister ID. In this case, the third party is responsible for maintaining the canister and
the local user must ensure that they have the correct canister ID. dfx will return the provided canister ID with no
further checks.
If a canister is typically deployed to the same canister ID on the mainnet, the user may set a remote
canister ID for the __default network. In this case, dfx canister id $CANISTER_NAME will return the default canister
ID for all networks that don't have a dedicated entry.
Basic usage
dfx canister id <canister_name>
Arguments
You can use the following argument with the dfx canister id command.
| Argument | Description |
|---|---|
canister_name | Specifies the name of the canister for which you want to display an identifier. |
Examples
To display the canister identifier for the hello_world canister, you can run the following command:
dfx canister id hello_world
The command displays output similar to the following:
75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
dfx canister info
Use the dfx canister info command to output a canister's controller and installed Wasm module hash.
Basic usage
dfx canister info <canister>
Arguments
You can use the following argument with the dfx canister info command.
| Argument | Description |
|---|---|
canister | Specifies the name or ID of the canister for which you want to display data. |
Examples
To get data about the hello_world canister, you can run the following command:
dfx canister info hello_world
The command displays output similar to the following:
Controllers: owdog-wiaaa-aaaad-qaaaq-cai
Module hash: 0x2cfb6f216fd6ab367364c02960afbbc5c444f5481225ee676992ac9058fd41e3
dfx canister install
Use the dfx canister install command to install compiled code as a canister on the mainnet or the local development environment.
Basic usage
dfx canister install [option] [--all | canister_name]
Options
You can use the following options with the dfx canister install command.
| Option | Description |
|---|---|
--argument <argument> | Specifies an argument to pass to the canister during installation. |
--argument-type <argument-type> | Specifies the data type for the argument when making the call using an argument [possible values: idl, raw] |
--argument-file <argument-file> | Specifies the file from which to read the argument to pass to the init method. Stdin may be referred to as -. |
--async-call | Enables you to continue without waiting for the result of the installation to be returned by polling the Internet Computer or the local development environment. |
-m, --mode <mode> | Specifies whether you want to install, reinstall, or upgrade canisters. Defaults to install. For more information about installation modes and canister management, see managing canisters. |
--no-wallet | Performs the call with the user identity as the sender of messages. Bypasses the wallet canister. Enabled by default. |
--no-asset-upgrade | Skips upgrading the asset canister, to only install the assets themselves. |
--upgrade-unchanged | Upgrade the canister even if the .wasm did not change. |
--wasm <file.wasm> | Specifies a particular Wasm file to install, bypassing the dfx.json project settings. |
--skip-pre-upgrade | Skip the pre_upgrade hook on upgrade. This requires the upgrade/auto mode. |
--wasm-memory-persistence <mode> | Keep or replace the Wasm main memory on upgrade. Possible values: keep, replace. This requires the upgrade/auto mode. |
Specifies the argument to pass to the init entrypoint
With --argument-type, you can specify the data format for the argument when you install using the --argument option. The valid values are idl and raw. By default, you can specify arguments using the Candid (idl) syntax for data values. For information about using Candid and its supported types, see Interact with a service in a terminal and Supported types. You can use raw as the argument type if you want to pass raw bytes to a canister.
Arguments
You can use the following arguments with the dfx canister install command.
| Argument | Description |
|---|---|
--all | Enables you to install multiple canisters at once if you have a project dfx.json file that includes multiple canisters. Note that you must specify --all or an individual canister name. |
canister_name | Specifies the name of the canister to deploy. If you are not using the --all option, the canister name is a required argument and should match the name you have configured for a project in the canisters section of the dfx.json configuration file. |
Examples
You can use the dfx canister install command to deploy Wasm you have compiled using the dfx build command as
a canister on the mainnet or on the local development environment. The most common use case is to
install all of the canisters by running the following command:
dfx canister install --all
Installing a specific canister
You can also use the dfx canister install command to deploy a specific canister instead of all of the canisters in
your project. For example, if you have a project with a hello_world_backend canister and a hello_world_frontend
canister but only want to deploy the hello_world_backend canister, you can deploy just that the canister by running
the following command:
dfx canister install hello_world_backend
Sending an asynchronous request
If you want to submit a request to install the canister and return a request identifier to check on the status of your request later instead of waiting for the command to complete, you can run a command similar to the following:
dfx canister install hello_world_backend --async
This command submits a request to install the canister and returns a request identifier similar to the following:
0x58d08e785445dcab4ff090463b9e8b12565a67bf436251d13e308b32b5058608
You can then use the request identifier to check the status of the request at a later time, much like a tracking number if you were shipping a package.
Overriding the default deployment options
If you want to deploy a canister on a custom local network without changing the settings in your dfx.json configuration file, you
can explicitly specify the custom local network you want to connect to by using the --network option.
For example, you can specify a custom network URL by running a command similar to the following:
dfx canister install --all --network http://192.168.3.1:5678
dfx canister logs
Use the dfx canister logs command to display the logs from a canister.
Basic usage
dfx canister logs [options] <canister-name>
Arguments
You must specify the following arguments for the dfx canister logs command.
| Argument | Description |
|---|---|
<canister> | Specifies the name or id of the canister to get the logs of. |
Options
You can specify the following options for the dfx canister logs command.
| Option | Description |
|---|---|
--follow | Fetches logs continuously until interrupted with Ctrl+C. |
--interval <interval> | Specifies the interval in seconds between log fetches when following logs. Defaults to 2 seconds. |
--since <since> | Shows the logs newer than a relative duration, with the valid units s, m, h, d. |
--since-time <since-time> | Shows the logs newer than a specific timestamp. Required either nanoseconds since Unix epoch or RFC3339 format (e.g. 2021-05-06T19:17:10.000000002Z). |
--tail <tail> | Shows the last number of the logs. |
Examples
To display the logs from the hello_world canister, you can run the following command:
dfx canister logs hello_world
The command displays output similar to the following:
[42. 2021-05-06T19:17:10.000000001Z]: Some text message
[43. 2021-05-06T19:17:10.000000002Z]: (bytes) 0xc0ffee
[44. 2021-05-06T19:17:15.000000001Z]: Five seconds later
[45. 2021-05-06T19:17:15.000000002Z]: (bytes) 0xc0ffee
To display the most recent log, you can run the following command:
dfx canister logs hello_world --tail 1
The command displays output similar to the following:
[45. 2021-05-06T19:17:15.000000002Z]: (bytes) 0xc0ffee
To display the logs for the past 3 seconds, you can run the following command:
dfx canister logs hello_world --since=3s
The command displays output similar to the following:
[44. 2021-05-06T19:17:15.000000001Z]: Five seconds later
[45. 2021-05-06T19:17:15.000000002Z]: (bytes) 0xc0ffee
To display the logs since a given time, you can run the following command:
dfx canister logs hello_world --since-time=2021-05-06T19:17:13.000000001Z
The command displays output similar to the following:
[44. 2021-05-06T19:17:15.000000001Z]: Five seconds later
[45. 2021-05-06T19:17:15.000000002Z]: (bytes) 0xc0ffee
To fetch logs continuously, you can run the following command:
dfx canister logs hello_world --follow
dfx canister metadata
Use the dfx canister metadata command to display metadata stored in a canister's Wasm module.
Basic usage
dfx canister metadata <canister-name> <metadata-name>
Arguments
You can use the following arguments with the dfx canister metadata command.
| Argument | Description |
|---|---|
canister | Specifies the name or id of the canister for which you want to display metadata. |
metadata-name | Specifies the name of the metadata which you want to display. |
Examples
To display the Candid service metadata for the hello_world canister, you can run the following command:
dfx canister metadata hello_world candid:service
The command displays output similar to the following:
service : {
greet: (text) -> (text);
}
dfx canister request-status
Use the dfx canister request-status command to request the status of a call to a canister. This command
requires you to specify the request identifier you received after invoking a method on the canister. The request
identifier is an hexadecimal string starting with 0x.
Basic usage
dfx canister request-status [options] <request-id> <canister>
Options
You can use the following options with the dfx canister request-status command.
| Option | Description |
|---|---|
--output <output> | Specifies the format for displaying the method's return result. Possible values are idl, raw and pp, where pp is equivalent to idl, but is pretty-printed. |
Arguments
You can specify the following argument for the dfx canister request-status command.
| Argument | Description |
|---|---|
request_id | Specifies the hexadecimal string returned in response to a dfx canister call or dfx canister install command. This identifier is an hexadecimal string starting with 0x. |
canister | Specifies the name or ID of the canister onto which the request was made. If the request was made to the management canister, specify the ID of the canister it is updating/querying. If the call was proxied by the cycles wallet, i.e. a dfx canister call --async --wallet=<ID> flag, specify the wallet canister ID. |
Examples
You can use the dfx canister request-status command to check on the status of a canister state change or to verify
that a call was not rejected by running a command similar to the following:
dfx canister request-status 0x58d08e785445dcab4ff090463b9e8b12565a67bf436251d13e308b32b5058608 backend
This command displays an error message if the request identifier is invalid or refused by the canister.
dfx canister send
Use the dfx canister send command after signing a message with the dfx canister sign command when you want to
separate these steps, rather than using the single dfx canister call command. Using separate calls can add security to
the transaction.
For example, when creating your neuron stake, you might want to use the dfx canister sign command to create a
signed message.json file using an air-gapped computer, then use the dfx canister send command to deliver the signed
message.
Basic usage
dfx canister send [options] <file_name>
Arguments
You can specify the following argument for the dfx canister send command.
| Argument | Description |
|---|---|
file_name | Specifies the file name of the message. |
dfx canister set-id
Use the dfx canister set-id command to set the canister identifier/principal for a specific canister name.
Note that you can only run this command from within the project directory structure. For example, if your project name
is hello_world, your current working directory must be the hello_world top-level project directory or one of its
subdirectories.
Basic usage
dfx canister set-id <canister_name> <principal>
Arguments
You can use the following argument with the dfx canister set-id command.
| Argument | Description |
|---|---|
canister_name | Specifies the name of the canister for which you want to set an identifier. |
principal | Specifies the principal of the canister for which you want to set an identifier. |
Options
You can use the following options with the dfx canister set-id command.
| Option | Description |
|---|---|
--network | The network for which you want to set the ID. |
Examples
You can use the dfx canister set-id command to set the canister identifier for a specific canister name.
dfx canister set-id hello_backend qhbym-qaaaa-aaaaa-aaafq-cai
The command displays output similar to the following:
Set canister id for hello_backend to qhbym-qaaaa-aaaaa-aaafq-cai
dfx canister sign
Use the dfx canister sign command before sending a message with the dfx canister send command when you want to
separate these steps rather than using the single dfx canister call command. Using separate calls can add security to
the transaction. For example, when creating a neuron stake, you might want to use the dfx canister sign command to
create a signed message.json file using an air-gapped computer, then use the dfx canister send command to deliver
the signed message from a computer connected to the internet.
Basic usage
dfx canister sign [options] <canister-name> <method-name> [argument]
Options
You can specify the following options for the dfx canister sign command.
| Option | Description |
|---|---|
--argument-file <file> | Specifies the file from which to read the argument to pass to the method. Stdin may be referred to as -. |
--expire-after <seconds> | Specifies how long the message will be valid before it expires and cannot be sent. Specify in seconds. If not defined, the default is 300s (5m). |
--file <output> | Specifies the output file name. The default is message.json. |
--query | Sends a query request to a canister. |
--random <random> | Specifies the configuration for generating random arguments. |
--type <type> | Specifies the data type for the argument when making a call using an argument. Possible values are idl and raw. |
--update | Sends an update request to the canister. This is the default method if the --query method is not used. |
Arguments
You can specify the following arguments for the dfx canister sign command.
| Argument | Description |
|---|---|
canister_name | Specifies the name of the canister to call. The canister name is a required argument and should match the name you have configured for a project in the canisters section of the dfx.json configuration file. |
method_name | Specifies the method name to call on the canister. The canister method is a required argument. |
argument | Specifies the argument to pass to the method |
Specify an argument to pass to the method
Depending on your program logic, an argument can be a required or optional argument. You can specify a data format type using the --type option if you pass an argument to the canister. By default, you can specify arguments using the Candid (idl) syntax for data values. You can use raw as the argument type if you want to pass raw bytes.
Examples
Use the dfx canister sign command to create a signed message.json file using the selected identity by running a
command similar to the following:
dfx canister sign --network=ic --expire-after=1h rno2w-sqaaa-aaaaa-aaacq-cai create_neurons ‘(“PUBLIC_KEY”)’
This command illustrates how to create a message.json file to create neurons on the mainnet (specified by
the ic alias) that is signed using your principal identifier as the message sender and with an expiration window that
ends in one hour.
Note that the time allotted to send a signed message is a fixed 5-minute window. The --expire-after option enables you
to specify the point in time when the 5-minute window for sending the signed message should end. For example, if you set
the --expire-after option to one hour (1h), you must wait at least 55 minutes before you send the generated message
and the signature for the message is only valid during the 5-minute window ending in the 60th minute.
In this example, therefore, you would need to send the message after 55 minutes and before 60 minutes for the message to be recognized as valid.
If you don’t specify the --expire-after option, the default expiration is five minutes.
dfx canister snapshot create
Use the dfx canister snapshot create command to create a snapshot of a stopped canister.
It can later be applied with dfx canister snapshot load to reset the canister to that state.
At both times, the canister must be stopped with dfx canister stop.
Basic usage
dfx canister snapshot create <canister> [--replace <replace>]
Arguments
You can use the following arguments with the dfx canister snapshot create command.
| Argument | Description |
|---|---|
<canister> | The canister to snapshot. |
--replace <replace> | If a snapshot ID is specified, the snapshot identified by this ID will be deleted and a snapshot with a new ID will be returned. |
Examples
Use the dfx canister snapshot create command to take a snapshot of canister hello:
dfx canister stop hello
dfx canister snapshot create hello
dfx canister start hello
To replace an existing snapshot:
dfx canister stop hello
dfx canister snapshot create hello --replace a1b2c3d4
dfx canister start hello
dfx canister snapshot load
Use the dfx canister snapshot load command to load a canister snapshot previously taken with dfx canister snapshot create.
At both times, the canister must be stopped with dfx canister stop.
Basic usage
dfx canister snapshot load <canister> <snapshot>
Arguments
You can use the following arguments with the dfx canister snapshot load command.
| Argument | Description |
|---|---|
<canister> | The canister to load the snapshot in. |
<snapshot> | The ID of the snapshot to load. |
Examples
Use the dfx canister snapshot load command to load a previously-taken snapshot in canister hello, deleting any data since the snapshot was taken:
dfx canister snapshot load hello 1a2b3c4d
dfx canister snapshot delete
Use the dfx canister snapshot delete command to delete a canister snapshot previously taken with dfx canister snapshot create.
Basic usage
dfx canister snapshot delete <canister> <snapshot>
Arguments
You can use the following arguments with the dfx canister snapshot delete command.
| Argument | Description |
|---|---|
<canister> | The canister to delete the snapshot from. |
<snapshot> | The ID of the snapshot to delete. |
Examples
Use the dfx canister snapshot delete command to delete a snapshot from canister hello:
dfx canister snapshot delete hello 1a2b3c4d
dfx canister snapshot list
Use the dfx canister snapshot list command to display all saved snapshots for a canister. They can be loaded with dfx canister snapshot load or deleted with dfx canister snapshot delete.
Basic usage
dfx canister snapshot list <canister>
Arguments
You can use the following arguments with the dfx canister snapshot list command.
| Argument | Description |
|---|---|
<canister> | The canister to list snapshots from. |
Examples
Use the dfx canister snapshot list command to list the snapshots in canister hello:
dfx canister snapshot list hello
dfx canister snapshot download
Use the dfx canister snapshot download command to download an existing canister snapshot to a given directory. The downloaded data can be uploaded with dfx canister snapshot upload.
Basic usage
dfx canister snapshot download <canister> <snapshot> --dir <DIR>
Arguments
You can use the following arguments with the dfx canister snapshot download command.
| Argument | Description |
|---|---|
<canister> | The canister to download the snapshot from. |
<snapshot> | The ID of the snapshot to download. |
--dir <dir> | The directory to download the snapshot to. It should be created and empty. |
Examples
Use the dfx canister snapshot download command to download the snapshot 0000000000000000ffffffffff9000010101 in canister hello to the output directory:
dfx canister snapshot download hello 0000000000000000ffffffffff9000010101 --dir output
dfx canister snapshot upload
Use the dfx canister snapshot upload command to upload a downloaded snapshot from a given directory to a canister.
Basic usage
dfx canister snapshot upload <canister> --dir <DIR>
Arguments
You can use the following arguments with the dfx canister snapshot upload command.
| Argument | Description |
|---|---|
<canister> | The canister to upload the snapshot to. |
--dir <dir> | The directory to upload the snapshot from. |
--replace <replace> | If a snapshot ID is specified, the snapshot identified by this ID will be deleted and a snapshot with a new ID will be returned. |
Examples
Use the dfx canister snapshot upload command to upload a downloaded snapshot from the output directory to canister hello:
dfx canister snapshot upload hello --dir output
dfx canister start
Use the dfx canister start command to restart a stopped canister on the mainnet or the local development environment.
In most cases, you run this command after you have stopped a canister to properly terminate any pending requests as a prerequisite to upgrading the canister.
Note that you can only run this command from within the project directory structure. For example, if your project name
is hello_world, your current working directory must be the hello_world top-level project directory or one of its
subdirectories.
Basic usage
dfx canister start [--all | canister_name]
Arguments
You can use the following arguments with the dfx canister start command.
| Argument | Description |
|---|---|
--all | Starts all of the canisters configured in the dfx.json file. Note that you must specify --all or an individual canister name. |
canister_name | Specifies the name of the canister you want to start. Note that you must specify either a canister name or the --all option. |
Examples
To start the hello_world canister, you can run the following command:
dfx canister start hello_world
To start all of the canisters you have deployed on the mainnet, you can run the following command:
dfx canister start --all --network=ic
dfx canister status
Use the dfx canister status command to check whether a canister is currently running, in the process of stopping, or
currently stopped on the mainnet or the local development environment.
Note that you can only run this command from within the project directory structure. For example, if your project name
is hello_world, your current working directory must be the hello_world top-level project directory or one of its
subdirectories.
Basic usage
dfx canister status [--all | canister_name]
Arguments
You can use the following arguments with the dfx canister status command.
| Argument | Description |
|---|---|
--all | Returns status information for all of the canisters configured in the dfx.json file. Note that you must specify --all or an individual canister name. |
--impersonate <principal> | Specifies a principal on behalf of which requests to a local PocketIC instance are sent. |
canister_name | Specifies the name of the canister you want to return information for. Note that you must specify either a canister name or the --all option. |
Examples
You can use the dfx canister status command to check the status of a specific canister or all canisters.
To check the status of the hello_world canister, you can run the following command:
dfx canister status hello_world
To check the status for all of the canisters within your current project that have deployed on the mainnet, you can run the following command:
dfx canister status --all --network=ic
dfx canister stop
Use the dfx canister stop command to stop a canister that is currently running on the mainnet or on the
local development environment.
In most cases, you run this command to properly terminate any pending requests as a prerequisite to upgrading the canister.
Note that you can only run this command from within the project directory structure. For example, if your project name
is hello_world, your current working directory must be the hello_world top-level project directory or one of its
subdirectories.
Basic usage
dfx canister stop [--all | canister_name]
Arguments
You can use the following arguments with the dfx canister stop command.
| Argument | Description |
|---|---|
--all | Stops all of the canisters configured in the dfx.json file. Note that you must specify --all or an individual canister name. |
canister_name | Specifies the name of the canister you want to stop. Note that you must specify either a canister name or the --all option. |
Examples
You can use the dfx canister stop command to stop a specific canister or all canisters.
To stop the hello_world canister, you can run the following command:
dfx canister stop hello_world
To stop all of the canisters within your project that you have deployed on the mainnet, you can run the following command:
dfx canister stop --all --network=ic
dfx canister uninstall-code
Use the dfx canister uninstall-code command to uninstall the code that a canister that is currently running on the
mainnet or on the local development environment.
This method removes a canister’s code and state, making the canister empty. Only the controller of the canister can uninstall code. Uninstalling a canister’s code will reject all calls that the canister has not yet responded to, and drop the canister’s code and state. Outstanding responses to the canister will not be processed, even if they arrive after code has been installed again. The canister is now empty.
Note that you can only run this command from within the project directory structure. For example, if your project name
is hello_world, your current working directory must be the hello_world top-level project directory or one of its
subdirectories.
Basic usage
dfx canister uninstall-code [--all | canister_name]
Arguments
You can use the following arguments with the dfx canister uninstall-code command.
| Argument | Description |
|---|---|
--all | Uninstalls all of the canisters configured in the dfx.json file. Note that you must specify --all or an individual canister name. |
canister_name | Specifies the name of the canister you want to uninstall. Note that you must specify either a canister name or the --all option. |
Examples
To uninstall the hello_world canister, you can run the following command:
dfx canister uninstall-code hello_world
To uninstall all of the canisters within your project that you have deployed on the mainnet, you can run the following command:
dfx canister uninstall-code --all --network=ic
dfx canister update-settings
Use the dfx canister update-settings command to update the settings of a canister running in the local development environment.
In most cases, you run this command to tune the amount of resources allocated to your canister.
Note that you can only run this command from within the project directory structure. For example, if your project name
is hello_world, your current working directory must be the hello_world top-level project directory or one of its
subdirectories.
Basic usage
dfx canister update-settings [options] [canister_name | --all]
Options
You can specify the following options for the dfx canister update-settings command.
| Option | Description |
|---|---|
--add-controller <principal> | Add a principal to the list of controllers of the canister. |
--add-log-viewer <principal> | Add a principal to the list of log viewers of the canister. Can be specified more than once to add multiple log viewers. If current log visibility is public or controllers, it will be changed to the custom allowed viewer list. |
-c, --compute-allocation <allocation> | Specifies the canister's compute allocation. This should be a percent in the range [0..100]. |
--confirm-very-long-freezing-threshold | Freezing thresholds above ~1.5 years require this option as confirmation. |
--confirm-very-short-freezing-threshold | Freezing thresholds below 1 week require this option as confirmation. |
--impersonate <principal> | Specifies a principal on behalf of which requests to a local PocketIC instance are sent. |
--set-controller <principal> | Specifies the identity name or the principal of the new controller. Can be specified more than once, indicating the canister will have multiple controllers. If any controllers are set with this parameter, any other controllers will be removed. |
--set-log-viewer <principal> | Specifies the principal of the log viewer of the canister. Can be specified more than once, indicating the canister will have multiple log viewers. If any log viewers are set with this parameter, any other log viewers will be removed. If current log visibility is public or controllers, it will be changed to the custom allowed viewer list. |
--memory-allocation <allocation> | Specifies how much memory the canister is allowed to use in total. This should be a value in the range [0..12 GiB]. A setting of 0 means the canister will have access to memory on a "best-effort" basis: It will only be charged for the memory it uses, but at any point in time may stop running if it tries to allocate more memory when there isn't space available on the subnet. |
--reserved-cycles-limit <limit> | Specifies the upper limit of the canister's reserved cycles. |
--wasm-memory-limit <limit> | Specifies a soft upper limit for the canister's heap memory. |
--log-visibility <visibility> | Specifies who is allowed to read the canister's logs. Can be either "controllers" or "public". For custom allowed viewers, use --set-log-viewer or --add-log-viewer. |
--remove-controller <principal> | Removes a principal from the list of controllers of the canister. |
--remove-log-viewer <principal> | Removes a principal from the list of log viewers of the canister. Can be specified more than once to remove multiple log viewers. |
--freezing-threshold <seconds> | Set the freezing threshold in seconds for a canister. This should be a value in the range [0..2^64^-1]. Very long thresholds require the --confirm-very-long-freezing-threshold option. |
--wasm-memory-threshold <threshold> | Specifies a threshold remaining amount of memory before the canister's low-memory hook runs. |
-y, --yes | Skips yes/no checks by answering 'yes'. Such checks can result in loss of control, so this is not recommended outside of CI. |
Arguments
You can use the following arguments with the dfx canister update-settings command.
| Argument | Description |
|---|---|
--all | Updates all canisters you have specified in dfx.json. You must specify either canister name/id or the --all option. |
canister_name | Specifies the name of the canister you want to update. You must specify either canister name/id or the --all option. |
Examples
To update the settings of the hello_world canister, you can run the following command:
dfx canister update-settings --freezing-threshold 2592000 --compute-allocation 99 hello_world
dfx canister url
Use the dfx canister url command to output the canister url for a specific canister.
Note that you can only run this command from within the project directory structure. For example, if your project name
is hello_world, your current working directory must be the hello_world top-level project directory or one of its
subdirectories.
If the canister has been deployed locally, the locally stored canister ID will be provided within the URL.
You can check the .dfx/local/canister_ids.json file in the project directory for details.
If a canister has been deployed by a third party on the mainnet, the user may set the .canisters[$CANISTER_NAME].remote[$NETWORK]
entry in dfx.json to the canister ID. In this case, the third party is responsible for maintaining the canister and
the local user must ensure that they have the correct canister ID. dfx will use the provided canister ID with no
further checks.
Basic usage
dfx canister url <canister>
Arguments
You can use the following argument with the dfx canister url command.
| Argument | Description |
|---|---|
canister | Specifies the name or id of the canister for which you want to display the url. |
Examples
To display the canister URL for the hello_world_backend canister, you can run the following command:
dfx canister url hello_world_backend
The command displays output similar to the following:
http://127.0.0.1:4943/?canisterId=erxue-5aaaa-aaaab-qaagq-cai&id=bkyz2-fmaaa-aaaaa-qaaaq-cai
The erxue-5aaaa-aaaab-qaagq-cai is the local canister id for __Candid_UI canister. You need to run dfx deploy
to generate the local __Candid_UI entry in .dfx/local/canister_ids.json first.
If you run:
dfx canister url hello_world_backend --network ic
The command displays output similar to the following:
https://a4gq6-oaaaa-aaaab-qaa4q-cai.raw.icp0.io/?id=bkyz2-fmaaa-aaaaa-qaaaq-cai
The a4gq6-oaaaa-aaaab-qaa4q-cai is the canister id for __Candid_UI canister on the mainnet.