diff --git a/docs/cli-reference/dfx-canister.md b/docs/cli-reference/dfx-canister.md index 1f2ba99050..e4a630587f 100644 --- a/docs/cli-reference/dfx-canister.md +++ b/docs/cli-reference/dfx-canister.md @@ -1,11 +1,11 @@ # dfx canister -Use the `dfx canister` command with flags and subcommands to manage canister operations and interaction with the {platform} or the local canister execution environment. In most cases, you use `dfx canister` subcommands after you compile a program to manage the canister lifecycle and to perform key tasks such as calling program functions. +Use the `dfx canister` command with flags and subcommands to manage canister operations and interaction with the Internet Computer or the local canister execution environment. In most cases, you use `dfx canister` subcommands after you compile a program to manage the canister lifecycle and to perform key tasks such as calling program functions. The basic syntax for running `dfx canister` commands is: ``` bash -dfx canister [subcommand] [flag] +dfx canister [canister flags] subcommand [subcommand flags] ``` Depending on the `dfx canister` subcommand you specify, additional arguments, options, and flags 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: @@ -16,28 +16,28 @@ dfx canister call --help For reference information and examples that illustrate using `dfx canister` commands, select an appropriate command. -| Command | Description | -|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`call`](#dfx-canister-call) | Calls a specified method on a deployed | -| [`create`](#dfx-canister-create) | Creates a new "empty" canister by registering a canister identifier on the {platform} or the local canister execution environment. | -| [`delete`](#dfx-canister-delete) | Deletes a currently stopped canister. | -| [`deposit-cycles`](#dfx-canister-deposit-cycles) | Deposit cycles into the specified canister. | -| `help` | Displays usage information message for a specified subcommand. | -| [`id`](#dfx-canister-id) | Displays the identifier for a canister. | -| [`info`](#dfx-canister-info) | Get the hash of a canister’s WASM module and its current controller in a certified way. | -| [`install`](#dfx-canister-install) | Installs compiled code as a canister on the {platform} or the local canister execution environment. | -| [`request-status`](#dfx-canister-request-status) | Requests the status of a call to a canister. | -| [`send`](#dfx-canister-send) | Send a previously-signed `message.json` to a specified canister identifier. For example, if you want to send a message that calls the network nervous system (NNS) governance canister to manage neurons, you might want to separate message signing from message delivery for security reasons. | -| [`sign`](#dfx-canister-send) | Create a signed `message.json` file before making a call to a specified canister identifier. For example, if you want to send a message that calls the network nervous system (NNS) governance canister to manage neurons, you might want to separate message signing from message delivery for security reasons. | -| [`start`](#dfx-canister-start) | Restarts a stopped canister. | -| [`status`](#dfx-canister-status) | Requests the running status of a canister. | -| [`stop`](#dfx-canister-stop) | Stops a currently running canister. | -| [`uninstall-code`](#dfx-canister-uninstall-code) | Uninstalls a canister, removing its code and state, on the Internet Computer network. | -| [`update-settings`](#dfx-canister-update-settings) | Update one or more of a canister's settings (i.e its controller, compute allocation, or memory allocation.). | +| Command | Description | +|----------------------------------------------------|---------------------------------------------------| +| [`call`](#dfx-canister-call) | Calls a specified method on a deployed canister. | +| [`create`](#dfx-canister-create) | Creates an empty canister and associates the assigned Canister ID to the canister name. | +| [`delete`](#dfx-canister-delete) | Deletes a currently stopped canister. | +| [`deposit-cycles`](#dfx-canister-deposit-cycles) | Deposit cycles into the specified canister. | +| `help` | Displays usage information message for a specified subcommand. | +| [`id`](#dfx-canister-id) | Displays the identifier of a canister. | +| [`info`](#dfx-canister-info) | Get the hash of a canister’s WASM module and its current controller. | +| [`install`](#dfx-canister-install) | Installs compiled code in a canister. | +| [`request-status`](#dfx-canister-request-status) | Requests the status of a call to a canister. | +| [`send`](#dfx-canister-send) | Send a previously-signed message. | +| [`sign`](#dfx-canister-send) | Sign a canister call and generate message file. | +| [`start`](#dfx-canister-start) | Starts a stopped canister. | +| [`status`](#dfx-canister-status) | Returns the current status of a canister: Running, Stopping, or Stopped. | +| [`stop`](#dfx-canister-stop) | Stops a currently running canister. | +| [`uninstall-code`](#dfx-canister-uninstall-code) | Uninstalls a canister, removing its code and state. Does not delete the canister. | +| [`update-settings`](#dfx-canister-update-settings) | Update one or more of a canister's settings (i.e its controller, compute allocation, or memory allocation.). | ## Overriding the default deployment environment -By default, `dfx canister` commands run on the local canister execution environment specified in the `dfx.json` file. If you want to send a `dfx canister` subcommand to the {platform} or a testnet without changing the settings in your `dfx.json` configuration file, you can explicitly specify the URL to connect to using the `--network` option. +By default, `dfx canister` commands run on the local canister execution environment specified in the `dfx.json` file. If you want to send a `dfx canister` subcommand to the Internet Computer or a testnet 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 canister execution environment, you can run the following command: @@ -45,22 +45,42 @@ For example, to register unique canister identifiers for a project on the local dfx canister create --all ``` -If you want to register unique canister identifiers for the same project on the {platform}, you can run the following command: +If you want to register unique canister identifiers for the same project on the Internet Computer, you can run the following command: ``` bash dfx canister --network ic create --all ``` -The SDK comes with an alias of `ic`, which is configured to point to the {platform}. You can also pass a URL as a network option, or you can configure additional aliases in `dfx.json` under the `networks` configuration. +The SDK comes with an alias of `ic`, which is configured to point to the Internet Computer. You can also pass a URL as a network option, or you can configure additional aliases in `dfx.json` under the `networks` configuration. To illustrate, you can call a canister and function running on a testnet using a command similar to the following: ``` bash -dfx canister --network \http://192.168.3.1:5678 call counter get +dfx canister --network http://192.168.3.1:5678 call counter get ``` Note that you must specify the `--network` parameter before the canister operation (`create` or `call`) and any additional arguments such as the canister name (`counter`), and function (`get`). +## Performing a call through the wallet + +By default, most `dfx canister` commands to the Internet Computer are signed by and sent from your own principal. (Exceptions are commands that require cycles: `dfx canister create` and `dfx canister deposit-cycles`. Those automatically go through the wallet.) Occasionally, you may want to make a call from your wallet, e.g. when only your wallet is allowed to call a certain function. To send a call through your wallet, you can use the `--wallet` flag like this: + +``` bash +dfx canister --wallet status +``` + +As a concrete example, if you want to request the status of a canister on the ic that is only controlled by your wallet, you would do the following: + +``` bash +dfx identity --network ic get-wallet +``` + +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 (let's assume the canister is called `my_canister_name`) as follows: + +``` bash +dfx canister --network ic --wallet 22ayq-aiaaa-aaaai-qgmma-cai status +``` + ## dfx canister call Use the `dfx canister call` command to call a specified method on a deployed canister. @@ -75,31 +95,33 @@ dfx canister call [option] canister_name method_name [argument] [flag] You can use the following optional flags with the `dfx canister call` command. -| Flag | Description | -|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `--async` | Enables you to continue without waiting for the result of the call to be returned by polling the local canister execution environment or the {platform}. | -| `-h`, `--help` | Displays usage information. | -| `--query` | Enables you to send a query request to a deployed canister. For best performance, you should use this flag when you explicitly want to use the query method to retrieve information. For information about the difference between query and update calls, see [Canisters include both program and state](../../concepts/canisters-code#canister-state). | -| `--update` | Enables you to send an update request to a deployed canister. By default, canister calls use the update method. | -| `-V`, `--version` | Displays version information. | +| Flag | Description | +|-------------------|-----------------| +| `--async` | Specifies not to wait for the result of the call to be returned by polling the replica. Instead return a response ID. | +| `-h`, `--help` | Displays usage information. | +| `--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](../../concepts/canisters-code#canister-state). | +| `--update` | Sends an update request to a canister. This is the default if the method is not a query method. | ### Options You can use the following options with the `dfx canister call` command. -| Option | Description | -|---------------------|--------------------------------------------------------------------------------------------------------------------------| -| `--output ` | Specifies the output format to use when displaying a method’s return result. The valid values are `idl` and `raw`. | -| `--type ` | Specifies the data format for the argument when making the call using an argument. The valid values are `idl` and `raw`. | +| Option | Description | +|-------------------------|--------------| +| `--candid ` | Provide the .did file with which to decode the response. Overrides value from dfx.json for project canisters. | +| `--output ` | Specifies the output format to use when displaying a method’s return result. The valid values are `idl`, `pp` and `raw`. The `pp` option is equivalent to `idl`, but is pretty-printed. | +| `--random ` | Specifies the config for generating random arguments. | +| `--type ` | Specifies the data format for the argument when making the call using an argument. The valid values are `idl` and `raw`. | +| `--with-cycles `| Specifies the amount of cycles to send on the call. Deducted from the wallet. Requires `--wallet` as a flag 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 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 | 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. 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](../../developer-docs/build/languages/candid/candid-intro) (`idl`) syntax for data values. For information about using Candid and its supported types, see [Interact with a service in a terminal](../../developer-docs/build/languages/candid/candid-howto#idl-syntax) and [Supported types](../candid-ref.md). You can use `raw` as the argument type if you want to pass raw bytes to a canister. | ### Examples @@ -110,7 +132,7 @@ You can use the `dfx canister call` command to invoke specific methods—with or 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 canister execution environment or the {platform} 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. +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 canister execution environment or the Internet Computer 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 @@ -149,12 +171,10 @@ This example uses the raw data type to pass a hexadecimal to the `greet` functio ## dfx canister create -Use the `dfx canister create` command to register one or more canister identifiers without compiled code. You must be connected to the local canister execution environment or the {platform} to run this command. +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 canister execution environment or the Internet Computer 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. -The first time you run the `dfx canister create` command to register an identifier, your public/private key pair credentials are used to create a `default` user identity. The credentials for the `default` user are migrated from `$HOME/.dfinity/identity/creds.pem` to `$HOME/.config/dfx/identity/default/identity.pem`. - ### Basic usage ``` bash @@ -168,24 +188,27 @@ You can use the following optional flags with the `dfx canister create` command. | Flag | Description | |-------------------|-------------------------------| | `-h`, `--help` | Displays usage information. | -| `-V`, `--version` | Displays version information. | ### Options You can use the following options with the `dfx canister create` command. -| Option | Description | -|------------------------------------|------------------------------------------------------------------------------------------------------| -| `--with-cycles ` | Enables you to specify the initial number of cycles in a canister when it is created by your wallet. | +| Option | Description | +|-------------------------------------------|--------------| +| `-c`, `--compute-allocation ` | Specifies the canister's compute allocation. This should be a percent in the range [0..100]. | +| `--controller ` | Specifies the identity name or the principal of the new controller. | +| `--memory-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. | +| `--no-wallet` | Performs the call with the user Identity as the Sender of messages. Bypasses the Wallet canister. Enabled by default. | +| `--with-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. | ### 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. | +| 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 @@ -203,7 +226,7 @@ dfx canister create --with-cycles 8000000000000 --all ## dfx canister delete -Use the `dfx canister delete` command to delete a stopped canister from the local canister execution environment or on the {platform}. +Use the `dfx canister delete` command to delete a stopped canister from the local canister execution environment or the Internet Computer. By default, this withdraws remaining cycles to your 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. @@ -217,10 +240,11 @@ dfx canister delete [flag] [--all | canister_name] You can use the following optional flags with the `dfx canister delete` command. -| Flag | Description | -|-------------------|-------------------------------| -| `-h`, `--help` | Displays usage information. | -| `-V`, `--version` | Displays version information. | +| Flag | Description | +|-----------------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `--no-withdrawal` | Do not withdrawal cycles, just delete the canister. | +| `--withdraw-cycles-to-dank` | Withdraw cycles to dank with the current principal. | ### Arguments @@ -230,6 +254,8 @@ You can use the following arguments with the `dfx canister delete` command. |-----------------|------------------------------------------------------------------------------------------------------------------------------------| | `--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. | +| `--withdraw-cycles-to-canister ` | Withdraw cycles from canister(s) to the specified canister/wallet before deleting. | +| `--withdraw-cycles-to-dank-principal ` | Withdraw cycles to dank with the given principal. | ### Examples @@ -241,7 +267,7 @@ To delete the `hello_world` canister, you can run the following command: dfx canister delete hello_world ``` -To delete all of the canisters you have deployed on the `ic` {platform}, you can run the following command: +To delete all of the canisters you have deployed on the `ic` Internet Computer and configured in your `dfx.json`, you can run the following command: ``` bash dfx canister --network=ic delete --all @@ -266,7 +292,6 @@ You can use the following optional flags with the `dfx canister deposit-cycles` | Flag | Description | |-------------------|-------------------------------| | `-h`, `--help` | Displays usage information. | -| `-V`, `--version` | Displays version information. | ### Arguments @@ -295,7 +320,7 @@ 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. +Use the `dfx canister id` command to output 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. @@ -312,7 +337,6 @@ You can use the following optional flags with the `dfx canister id` command. | Flag | Description | |-------------------|-------------------------------| | `-h`, `--help` | Displays usage information. | -| `-V`, `--version` | Displays version information. | ### Arguments @@ -338,9 +362,52 @@ 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 + +``` bash +dfx canister info canister +``` + +### Flags + +You can use the following optional flags with the `dfx canister info` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | + +### 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 + +You can use the `dfx canister info` command to display the canister controller and installed WASM module. + +To the data about the `hello_world` canister, you can run the following command: + +``` bash +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 {platform} or on the local canister execution environment. +Use the `dfx canister install` command to install compiled code as a canister on the Internet Computer or on the local canister execution environment. ### Basic usage @@ -352,36 +419,37 @@ dfx canister install [flag] [option] [--all | canister_name] You can use the following optional flags with the `dfx canister install` command. -| Flag | Description | -|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `--async` | Enables you to continue without waiting for the result of the installation to be returned by polling the {platform} or the local canister execution environment. | -| `-h`, `--help` | Displays usage information. | -| `-V`, `--version` | Displays version information. | +| Flag | Description | +|-------------------|--------------| +| `--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 canister execution environment. | +| `-h`, `--help` | Displays usage information. | +| `--upgrade-unchanged` | Upgrade the canister even if the .wasm did not change. | ### Options You can use the following options with the `dfx canister install` command. -| Option | Description | -|---------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `--argument ` | Specifies an argument to pass to the canister during installation. | +| Option | Description | +|----------|--------------| +| `--argument ` | Specifies an argument to pass to the canister during installation. | | `--argument-type ` | Specifies 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](../../developer-docs/build/languages/candid/candid-intro) (`idl`) syntax for data values. For information about using Candid and its supported types, see [Interact with a service in a terminal](../../developer-docs/build/languages/candid/candid-howto#idl-syntax) and [Supported types](../candid-ref.md). You can use `raw` as the argument type if you want to pass raw bytes to a canister. | -| `-c`, `--compute-allocation ` | Defines a compute allocation—essentially the equivalent of setting a CPU allocation—for canister execution. You can set this value as a percentage in the range of 0 to 100. | -| `--memory-allocation ` | Specifies how much memory the canister is allowed to use in total. You can set this value in the range of 0 to 8MB. | -| `-m`, `--mode ` | Specifies whether you want to `install`, `reinstall`, or `upgrade` canisters. For more information about installation modes and canister management, see [Managing canisters](../../developer-docs/build/project-setup/manage-canisters). | +| `-c`, `--compute-allocation ` | Defines a compute allocation—essentially the equivalent of setting a CPU allocation—for canister execution. You can set this value as a percentage in the range of 0 to 100. | +| `--memory-allocation ` | Specifies how much memory the canister is allowed to use in total. You can set this value in the range of 0 to 8MB. | +| `-m`, `--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](../../developer-docs/build/project-setup/manage-canisters). | +| `--wasm ` | Specifies a particular WASM file to install, bypassing the dfx.json project settings. | ### 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. | +| 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 WebAssembly you have compiled using the `dfx build` command as a canister on the {platform} or on the local canister execution environment. The most common use case is to install all of the canisters by running the following command: +You can use the `dfx canister install` command to deploy WebAssembly you have compiled using the `dfx build` command as a canister on the Internet Computer or on the local canister execution environment. The most common use case is to install all of the canisters by running the following command: ``` bash dfx canister install --all @@ -413,12 +481,12 @@ You can then use the request identifier to check the status of the request at a #### Overriding the default deployment options -If you want to deploy a canister on a testnet without changing the settings in your `dfx.json` configuration file, you can explicitly specify the testnet you want to connect to by using the `+--network` option. +If you want to deploy a canister on a testnet without changing the settings in your `dfx.json` configuration file, you can explicitly specify the testnet you want to connect to by using the `--network` option. For example, you can specify a testnet URL by running a command similar to the following: ``` bash -dfx canister --network \http://192.168.3.1:5678 install --all +dfx canister --network http://192.168.3.1:5678 install --all ``` Note that you must specify the network parameter before the canister operation (`install`) and before the canister name or `--all` flag. @@ -444,7 +512,7 @@ Use the `dfx canister request-status` command to request the status of a specifi ### Basic usage ``` bash -dfx canister request-status request_id +dfx canister request-status request_id [option] ``` ### Flags @@ -454,7 +522,14 @@ You can use the following optional flags with the `dfx canister request-status` | Flag | Description | |-------------------|-------------------------------| | `-h`, `--help` | Displays usage information. | -| `-V`, `--version` | Displays version information. | + +### Options + +You can use the following options with the `dfx canister request-status` command. + +| Option | Description | +|----------|--------------| +| `--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 @@ -474,80 +549,6 @@ dfx canister request-status 0x58d08e785445dcab4ff090463b9e8b12565a67bf436251d13e This command displays an error message if the request identifier is invalid or refused by the canister. -### Basic usage - -``` bash -dfx canister set-controller [flag] canister new-controller -``` - -### Flags - -You can use the following optional flags with the `dfx canister set-controller` command. - -| Flag | Description | -|-------------------|-------------------------------| -| `-h`, `--help` | Displays usage information. | -| `-V`, `--version` | Displays version information. | - -### Arguments - -You must use the following arguments with the `dfx canister set-controller` command. - -| Argument | Description | -|--------------------|--------------------------------------------------------------------------------------------------------------------------------------| -| `` | Specifies the canister name or canister identifier to be controlled by the identity you specify using the *new_controller* argument. | -| `` | Specifies the identity name or principal of the controller. | - -### Examples - -You can use the `dfx canister set-controller` command to specify a user or canister as the controlling identity for a specific canister. - -For example, you might create a new identity called `pubsadmin` then run the `dfx canister set-controller` to specify that you want the `pubsadmin` identity to be the controller of the `hello_world` canister by running the following commands: - - dfx identity new pubsadmin - dfx canister set-controller hello_world pubsadmin - -To set the controlling identity using the textual representation of the identity principal, you might run a command similar to the following: - - dfx canister set-controller hello_world wcp5u-pietp-k5jz4-sdaaz-g3x4l-zjzxa-lxnly-fp2mk-j3j77-25qat-pqe - -Although specifying a user identity name or principal is one potential use case, a more common scenario is to specify the wallet canister that you want to use to send cycles to the canister. The following steps illustrate this scenario when you are doing local development. For this example, assume you have created a project called `open_sf` with two canisters deployed on the local canister execution environment. - -1. Create an identity—for example, `sf-controller`—to act as the controller. - - dfx identity new sf-controller - - Creating identity: "sf-controller". - Created identity: "sf-controller". - -2. Make the new identity the active identity. - - dfx identity use sf-controller - - Using identity: "sf-controller". - -3. Generate a wallet canister identifier for the new identity. - - dfx identity get-wallet - - Creating a wallet canister on the local canister execution environment. - r7inp-6aaaa-aaaaa-aaabq-cai - The wallet canister on the the local canister execution environment for user "sf-controller" is "r7inp-6aaaa-aaaaa-aaabq-cai" - -4. Switch the active identity to the current controller of the canister. For example, if the default identity was used to create the canister, you would run the following command: - - dfx identity use default - - Using identity: "default". - -5. Set the controller for a specified canister to use the wallet associated wit the sf-controller identity. - - dfx canister set-controller open_sf_assets r7inp-6aaaa-aaaaa-aaabq-cai - - Set "r7inp-6aaaa-aaaaa-aaabq-cai" as controller of "open_sf_assets". - - You can now use the wallet canister `r7inp-6aaaa-aaaaa-aaabq-cai` to send cycles or add custodians to the `open_sf_assets` 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. @@ -567,7 +568,7 @@ You can use the following optional flags with the `dfx canister request-status` | Flag | Description | |-------------------|-------------------------------| | `-h`, `--help` | Displays usage information. | -| `-V`, `--version` | Displays version information. | +| `--status` | Send the signed request-status call in the message. | ### Arguments @@ -585,7 +586,7 @@ Use the `dfx canister send` command to send a signed message created using the ` ## 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 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 from a computer connected to the {platform}. +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 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 from a computer connected to the Internet Computer. ### Basic usage @@ -602,61 +603,35 @@ You can use the following optional flags with the `dfx canister sign` command. | `-h`, `--help` | Displays usage information. | | `--query` | Sends a query request to a canister. | | `--update` | Sends an update request to the canister. This is the default method if the `--query` method is not used. | -| `-V`, `--version` | Displays version information. | ### Options You can specify the following options for the `dfx canister sign` command. - +| Option | Description | +|------------------------------|--------------| +| `--expire-after ` | 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 ` | Specifies the output file name. The default is `message.json`. | +| `--random ` | Specifies the configuration for generating random arguments. | +| `--type ` | Specifies the data type for the argument when making a call using an argument. Possible values are `idl` and `raw`. | ### 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 | 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. 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](../candid-ref.md) (`idl`) syntax for data values. For information about using Candid and its supported types, see [Interact with a service in a terminal](../../developer-docs/build/languages/candid/candid-howto#idl-syntax) and [Supported types](../candid-ref#supported-types). 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 principal associated with the identity you created using the Privacy Enhanced Mail (PEM) file by running a command similar to the following: +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 --network=ic sign --expire-after=1h rno2w-sqaaa-aaaaa-aaacq-cai create_neurons ‘(“PUBLIC_KEY”)’` -This command illustrates how to creates a `message.json` file to create neurons on the {platform} 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. +This command illustrates how to creates a `message.json` file to create neurons on the Internet Computer 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. @@ -670,7 +645,7 @@ Send the signed message to the genesis token canister (GTC) to create a neuron o ## dfx canister start -Use the `dfx canister start` command to restart a stopped canister on the {platform} or the local canister execution environment. +Use the `dfx canister start` command to restart a stopped canister on the Internet Computer or the local canister execution 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. @@ -679,7 +654,7 @@ Note that you can only run this command from within the project directory struct ### Basic usage ``` bash -dfx canister start [flag] [--all | canister_name] +dfx canister start [--all | canister_name] ``` ### Flags @@ -689,7 +664,6 @@ You can use the following optional flags with the `dfx canister start` command. | Flag | Description | |-------------------|-------------------------------| | `-h`, `--help` | Displays usage information. | -| `-V`, `--version` | Displays version information. | ### Arguments @@ -710,7 +684,7 @@ 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 `ic` {platform}, you can run the following command: +To start all of the canisters you have deployed on the `ic` Internet Computer, you can run the following command: ``` bash dfx canister --network=ic start --all @@ -718,14 +692,14 @@ dfx canister --network=ic start --all ## 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 {platform} or on the local canister execution environment. +Use the `dfx canister status` command to check whether a canister is currently running, in the process of stopping, or currently stopped on the Internet Computer or on the local canister execution 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 ``` bash -dfx canister status [flag] [--all | canister_name] +dfx canister status [--all | canister_name] ``` ### Flags @@ -735,7 +709,6 @@ You can use the following optional flags with the `dfx canister status` command. | Flag | Description | |-------------------|-------------------------------| | `-h`, `--help` | Displays usage information. | -| `-V`, `--version` | Displays version information. | ### Arguments @@ -756,7 +729,7 @@ To check the status of the `hello_world` canister, you can run the following com dfx canister status hello_world ``` -To check the status for all of the canisters you have deployed on the `ic` {platform}, you can run the following command: +To check the status for all of the canisters you have deployed on the `ic` Internet Computer, you can run the following command: ``` bash dfx canister --network=ic status --all @@ -764,7 +737,7 @@ dfx canister --network=ic status --all ## dfx canister stop -Use the `dfx canister stop` command to stop a canister that is currently running on the {platform} or on the local canister execution environment. +Use the `dfx canister stop` command to stop a canister that is currently running on the Internet Computer or on the local canister execution environment. In most cases, you run this command to properly terminate any pending requests as a prerequisite to upgrading the canister. @@ -773,7 +746,7 @@ Note that you can only run this command from within the project directory struct ### Basic usage ``` bash -dfx canister stop [flag] [--all | canister_name] +dfx canister stop [--all | canister_name] ``` ### Flags @@ -783,7 +756,6 @@ You can use the following optional flags with the `dfx canister stop` command. | Flag | Description | |-------------------|-------------------------------| | `-h`, `--help` | Displays usage information. | -| `-V`, `--version` | Displays version information. | ### Arguments @@ -804,7 +776,7 @@ To stop the `hello_world` canister, you can run the following command: dfx canister stop hello_world ``` -To stop all of the canisters you have deployed on the `ic` {platform}, you can run the following command: +To stop all of the canisters you have deployed on the `ic` Internet Computer, you can run the following command: ``` bash dfx canister --network=ic stop --all @@ -812,9 +784,9 @@ dfx canister --network=ic stop --all ## dfx canister uninstall-code -Use the `dfx canister uninstall-code` command to uninstall the code that a canister that is currently running on the {platform} or on the local canister execution environment. +Use the `dfx canister uninstall-code` command to uninstall the code that a canister that is currently running on the Internet Computer or on the local canister execution environment. -This method removes a canister’s code and state, making the canister empty again. 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. In particular, any incoming or queued calls will be rejected. +This method removes a canister’s code and state, making the canister empty again. 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. @@ -851,7 +823,7 @@ To uninstall the `hello_world` canister, you can run the following command: dfx canister uninstall-code hello_world ``` -To uninstall all of the canisters you have deployed on the `ic` {platform}, you can run the following command: +To uninstall all of the canisters you have deployed on the `ic` Internet Computer, you can run the following command: ``` bash dfx canister --network=ic uninstall-code --all @@ -868,31 +840,39 @@ Note that you can only run this command from within the project directory struct ### Basic usage ``` bash -dfx canister update-settings [flag] [canister_name] +dfx canister update-settings [flags] [options] [canister_name | --all] ``` ### Flags You can use the following optional flags with the `dfx canister update-settings` command. -| Flag | Description | -|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `--add-controller` | Add a principal to the list of controllers of the canister. | -| `-c`, `--compute-allocation` | Specifies the canister's compute allocation. This should be a percent in the range [0..100]. | -| `--controller` | Specifies the identity name or the principal of the new controller. | -| `-h`, `--help` | Displays usage information. | -| `--memory-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. | -| `--remove-controller` | Removes a principal from the list of controllers of the canister. | -| `--freezing-threshold` | Set the [freezing threshold](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-create_canister) in seconds for a canister. This should be a value in the range [0..2^64^-1]. | +| Flag | Description | +|-----------------------------------------|--------------| +| `-h`, `--help` | Displays usage information. | | `--confirm-very-long-freezing-threshold`| Freezing thresholds above ~1.5 years require this flag as confirmation. | +### Options + +You can specify the following options for the `dfx canister update-settings` command. + +| Option | Description | +|--------------------------------------------|--------------| +| `--add-controller ` | Add a principal to the list of controllers of the canister. | +| `-c`, `--compute-allocation ` | Specifies the canister's compute allocation. This should be a percent in the range [0..100]. | +| `--controller ` | Specifies the identity name or the principal of the new controller. | +| `--memory-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. | +| `--remove-controller ` | Removes a principal from the list of controllers of the canister. | +| `--freezing-threshold ` | Set the [freezing threshold](https://internetcomputer.org/docs/current/references/ic-interface-spec/#ic-create_canister) 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` flag. | + ### Arguments You can use the following arguments with the `dfx canister update-settings` command. | Argument | Description | |-----------------|---------------------------------------------------------| -| `canister_name` | Specifies the name of the canister you want to update. | +| `--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 diff --git a/docs/cli-reference/dfx-wallet.md b/docs/cli-reference/dfx-wallet.md index ac40d4cc66..5c7445cbef 100644 --- a/docs/cli-reference/dfx-wallet.md +++ b/docs/cli-reference/dfx-wallet.md @@ -88,7 +88,7 @@ You can use the following options with the `dfx canister call` command. |Option |Description| --------|------------| -|`--network ` |Specifies the environment (e.g., {platform} or testnet) of the controller you want to add. +|`--network ` |Specifies the environment (e.g., Internet Computer or testnet) of the controller you want to add. ### Arguments diff --git a/src/dfx/src/commands/canister/call.rs b/src/dfx/src/commands/canister/call.rs index cc1452849d..0e8415fe78 100644 --- a/src/dfx/src/commands/canister/call.rs +++ b/src/dfx/src/commands/canister/call.rs @@ -39,7 +39,7 @@ pub struct CanisterCallOpts { #[clap(long)] r#async: bool, - /// Sends a query request to a canister. + /// Sends a query request to a canister instead of an update request. #[clap(long, conflicts_with("async"))] query: bool, @@ -51,7 +51,7 @@ pub struct CanisterCallOpts { #[clap(conflicts_with("random"))] argument: Option, - /// Specifies the config for generating random argument. + /// Specifies the config for generating random arguments. #[clap(long, conflicts_with("argument"))] random: Option, @@ -66,6 +66,7 @@ pub struct CanisterCallOpts { /// Specifies the amount of cycles to send on the call. /// Deducted from the wallet. + /// Requires --wallet as a flag to `dfx canister`. #[clap(long, validator(cycle_amount_validator))] with_cycles: Option, diff --git a/src/dfx/src/commands/canister/create.rs b/src/dfx/src/commands/canister/create.rs index 5ab48052af..00d449c572 100644 --- a/src/dfx/src/commands/canister/create.rs +++ b/src/dfx/src/commands/canister/create.rs @@ -20,8 +20,7 @@ use ic_agent::Identity as _; use ic_types::principal::Principal as CanisterId; use slog::info; -/// Creates an empty canister on the Internet Computer and -/// associates the Internet Computer assigned Canister ID to the canister name. +/// Creates an empty canister and associates the assigned Canister ID to the canister name. #[derive(Parser)] pub struct CanisterCreateOpts { /// Specifies the canister name. Either this or the --all flag are required. @@ -46,7 +45,7 @@ pub struct CanisterCreateOpts { compute_allocation: Option, /// Specifies how much memory the canister is allowed to use in total. - /// This should be a value in the range [0..12 GiB] + /// 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. diff --git a/src/dfx/src/commands/canister/delete.rs b/src/dfx/src/commands/canister/delete.rs index 603f71f226..95f91cdf6e 100644 --- a/src/dfx/src/commands/canister/delete.rs +++ b/src/dfx/src/commands/canister/delete.rs @@ -36,7 +36,7 @@ const DANK_PRINCIPAL: Principal = const WITHDRAWAL_COST: u128 = 10_000_000_000; // Emperically estimated. const MAX_MEMORY_ALLOCATION: u64 = 8589934592; -/// Deletes a canister on the Internet Computer network. +/// Deletes a currently stopped canister. #[derive(Parser)] pub struct CanisterDeleteOpts { /// Specifies the name of the canister to delete. @@ -51,7 +51,7 @@ pub struct CanisterDeleteOpts { #[clap(long)] no_withdrawal: bool, - /// Withdraw cycles from canister(s) to canister/wallet before deleting. + /// Withdraw cycles from canister(s) to the specified canister/wallet before deleting. #[clap(long, conflicts_with("no-withdrawal"))] withdraw_cycles_to_canister: Option, diff --git a/src/dfx/src/commands/canister/info.rs b/src/dfx/src/commands/canister/info.rs index bdab1b05ad..2411d3fe59 100644 --- a/src/dfx/src/commands/canister/info.rs +++ b/src/dfx/src/commands/canister/info.rs @@ -10,10 +10,10 @@ use ic_types::Principal; use serde_cbor::Value; use std::convert::TryFrom; -/// Get the hash of a canister’s WASM module and its current controller in a certified way. +/// Get the hash of a canister’s WASM module and its current controller. #[derive(Parser)] pub struct InfoOpts { - /// Specifies the name or id of the canister to get its certified canister information. + /// Specifies the name or id of the canister to get its canister information. canister: String, } diff --git a/src/dfx/src/commands/canister/install.rs b/src/dfx/src/commands/canister/install.rs index a146539218..98dabde26b 100644 --- a/src/dfx/src/commands/canister/install.rs +++ b/src/dfx/src/commands/canister/install.rs @@ -18,7 +18,7 @@ use std::fs; use std::path::PathBuf; use std::str::FromStr; -/// Deploys compiled code as a canister on the Internet Computer. +/// Installs compiled code in a canister. #[derive(Parser, Clone)] pub struct CanisterInstallOpts { /// Specifies the canister to deploy. You must specify either canister name/id or the --all option. @@ -49,7 +49,7 @@ pub struct CanisterInstallOpts { #[clap(long, requires("argument"), possible_values(&["idl", "raw"]))] argument_type: Option, - /// Specifies a particular WASM file to install, bypassing the dfx.json project system. + /// Specifies a particular WASM file to install, bypassing the dfx.json project settings. #[clap(long, conflicts_with("all"))] wasm: Option, } diff --git a/src/dfx/src/commands/canister/request_status.rs b/src/dfx/src/commands/canister/request_status.rs index a91a037efa..677c7765c7 100644 --- a/src/dfx/src/commands/canister/request_status.rs +++ b/src/dfx/src/commands/canister/request_status.rs @@ -14,7 +14,7 @@ use ic_agent::{AgentError, RequestId}; use ic_types::Principal; use std::str::FromStr; -/// Requests the status of a specified call from a canister. +/// Requests the status of a call from a canister. #[derive(Parser)] pub struct RequestStatusOpts { /// Specifies the request identifier. diff --git a/src/dfx/src/commands/canister/send.rs b/src/dfx/src/commands/canister/send.rs index 5014dc65e9..1dca2aa2a6 100644 --- a/src/dfx/src/commands/canister/send.rs +++ b/src/dfx/src/commands/canister/send.rs @@ -12,7 +12,7 @@ use ic_types::Principal; use std::{fs::File, path::Path}; use std::{io::Read, str::FromStr}; -/// Send a signed message +/// Send a previously-signed message. #[derive(Parser)] pub struct CanisterSendOpts { /// Specifies the file name of the message diff --git a/src/dfx/src/commands/canister/sign.rs b/src/dfx/src/commands/canister/sign.rs index 94f5982dc1..c308d667f1 100644 --- a/src/dfx/src/commands/canister/sign.rs +++ b/src/dfx/src/commands/canister/sign.rs @@ -26,7 +26,7 @@ use std::path::Path; use std::str::FromStr; use std::time::SystemTime; -/// Sign a canister call and generate message file in json +/// Sign a canister call and generate message file. #[derive(Parser)] pub struct CanisterSignOpts { /// Specifies the name of the canister to call. @@ -54,7 +54,7 @@ pub struct CanisterSignOpts { #[clap(long, requires("argument"), possible_values(&["idl", "raw"]))] r#type: Option, - /// Specifies how long will the message be valid in seconds, default to be 300s (5 minutes) + /// Specifies how long the message will be valid in seconds, default to be 300s (5 minutes) #[clap(long, default_value("5m"))] expire_after: String, diff --git a/src/dfx/src/commands/canister/start.rs b/src/dfx/src/commands/canister/start.rs index 8b679e728f..12d8881bba 100644 --- a/src/dfx/src/commands/canister/start.rs +++ b/src/dfx/src/commands/canister/start.rs @@ -11,7 +11,7 @@ use ic_types::Principal; use slog::info; use std::time::Duration; -/// Starts a canister on the Internet Computer network. +/// Starts a stopped canister. #[derive(Parser)] pub struct CanisterStartOpts { /// Specifies the name or id of the canister to start. You must specify either a canister name/id or the --all flag. diff --git a/src/dfx/src/commands/canister/status.rs b/src/dfx/src/commands/canister/status.rs index edf0b425d8..3401f1cc08 100644 --- a/src/dfx/src/commands/canister/status.rs +++ b/src/dfx/src/commands/canister/status.rs @@ -12,7 +12,7 @@ use ic_types::Principal; use slog::info; use std::time::Duration; -/// Returns the current status of the canister on the Internet Computer network: Running, Stopping, or Stopped. +/// Returns the current status of a canister: Running, Stopping, or Stopped. #[derive(Parser)] pub struct CanisterStatusOpts { /// Specifies the name of the canister to return information for. diff --git a/src/dfx/src/commands/canister/stop.rs b/src/dfx/src/commands/canister/stop.rs index 141c23f82d..c8bddf595a 100644 --- a/src/dfx/src/commands/canister/stop.rs +++ b/src/dfx/src/commands/canister/stop.rs @@ -11,7 +11,7 @@ use ic_types::Principal; use slog::info; use std::time::Duration; -/// Stops a canister that is currently running on the Internet Computer network. +/// Stops a currently running canister. #[derive(Parser)] pub struct CanisterStopOpts { /// Specifies the name or id of the canister to stop. diff --git a/src/dfx/src/commands/canister/uninstall_code.rs b/src/dfx/src/commands/canister/uninstall_code.rs index 8b7c30fa42..675eafb027 100644 --- a/src/dfx/src/commands/canister/uninstall_code.rs +++ b/src/dfx/src/commands/canister/uninstall_code.rs @@ -11,7 +11,8 @@ use ic_types::Principal; use slog::info; use std::time::Duration; -/// Uninstalls a canister, removing its code and state, on the Internet Computer network. +/// Uninstalls a canister, removing its code and state. +/// Does not delete the canister. #[derive(Parser)] pub struct UninstallCodeOpts { /// Specifies the name or id of the canister to uinstall. diff --git a/src/dfx/src/commands/canister/update_settings.rs b/src/dfx/src/commands/canister/update_settings.rs index b09b644972..c1b7eaa01c 100644 --- a/src/dfx/src/commands/canister/update_settings.rs +++ b/src/dfx/src/commands/canister/update_settings.rs @@ -34,9 +34,11 @@ pub struct UpdateSettingsOpts { #[clap(long, multiple_occurrences(true))] controller: Option>, + /// Add a principal to the list of controllers of the canister. #[clap(long, multiple_occurrences(true), conflicts_with("controller"))] add_controller: Option>, + /// Removes a principal from the list of controllers of the canister. #[clap(long, multiple_occurrences(true), conflicts_with("controller"))] remove_controller: Option>,