Command-line reference

The DFINITY command-line execution environment (dfx) is the primary tool for creating, deploying, and managing the applications you develop for the Internet Computer platform.

dfx

Use the dfx parent command with flags and subcommands to specify the operations you want to perform with or without optional arguments.

Basic usage

dfx [option] [subcommand] [flag]

Flags

You can use the following optional flags with the dfx parent command or with any of the dfx subcommands.

Flag Description

-h, --help

Displays usage information.

-q`, --quiet

Suppresses informational messages.

-v, --verbose

Displays detailed information about operations.

-V, --version

Displays version information.

Options

You can use the following options with the dfx command.

Option Description

--logfile <logfile>

Writes log file messages to the specified log file name if you use the --log file logging option.

--log <logmode>

Specifies the logging mode to use. + You can set the log mode to one of the following:

- stderr to log messages to the standard error facility.

- tee to write messages to both standard output and to a specified file name.

- file to write messages to a specified file name.

The default logging mode is stderr.

Subcommands

Use the following subcommands to specify the operation you want to perform or to view usage information for a specific command.

Command Description

bootstrap

Starts the bootstrap server you want to use to serve front-end assets for your project.

build

Builds canister output from the source code in your project.

cache

Manages the dfx cache on the local computer.

canister

Manages canisters deployed on a network replica.

config

Sets or changes configuration options for your current project.

help

Displays usage information for a specified subcommand.

new

Creates a new project.

ping

Sends a response request to a specified Internet Computer network to determine network connectivity. If the connection is successful, the Internet Computer replies with its status.

replica

Starts a local network replica process.

start

Starts the local network replica and a web server for the current project.

stop

Stops the local network replica.

upgrade

Upgrades the version of dfx installed on the local computer to the latest version available.

Examples

You can use the dfx parent command to display usage information or version information. For example, to display information about the version of dfx you currently have installed, you can run the following command:

dfx --version

To view usage information for a specific subcommand, specify the subcommand and the --help flag. For example, to see usage information for dfx build, you can run the following command:

dfx build --help

You can use the --verbose and --quiet flags to increment or decrement the logging level. If you don’t specify any logging level, CRITICAL, ERROR, WARNING, and INFO messages are logged by default. Specifying one verbose flag (-v) increases the log level to include DEBUG messages. Specifying two verbose flags (-vv)increases the logging level to include both DEBUG and TRACE messages.

Adding a --quiet flag decreases the logging level. For example, to remove all messages, you can run a command similar the following:

dfx -qqqq build

Keep in mind that using TRACE level logging (--vv) generates a lot of log messages that can affect performance and should only be used when required for troubleshooting or analysis.

To output log messages to a file named newlog.txt and display the messages on your terminal when creating a new project, you can run a command similar to the following:

dfx --log tee --logfile newlog.txt new hello_world

dfx bootstrap

Use the dfx bootstrap command to start the bootstrap web server defined in the dfx.json configuration file or specified using command-line options.

The bootstrap web server you specify is used to serve the front-end static assets for your project.

Basic usage

dfx bootstrap [option]

Flags

You can use the following optional flags with the dfx bootstrap command.

Flag Description

-h, --help

Displays usage information.

-V, --version

Displays version information.

Options

You can specify the following options for the dfx bootstrap command.

Option Description

ip <ip_address>

Specifies the IP address that the bootstrap server listens on. If you don’t specify an IP address, the address setting you have configured in the dfx.json configuration file is used. By default, the server address is 127.0.0.1.

--network <network>

Specifies the network to connect to if you want to override the default local network endpoint (http://127.0.0.1:8080/api).

--port <port>

Specifies the port number that the bootstrap server listens on. By default, port number 8081 is used.

--root <root>

Specifies the directory containing static assets served by the bootstrap server. By default, the path to static assets is: $HOME/.cache/dfinity/versions/$DFX_VERSION/js-user-library/dist/bootstrap.

--timeout <timeout>

Specifies the maximum amount of time, in seconds, the bootstrap server will wait for upstream requests to complete. By default, the bootstrap server waits for a maximum of 30 seconds.

Examples

You can use the dfx bootstrap command to start a web server for your application using custom settings, including a specific server address, port number, and static asset location.

For example, to start the bootstrap server using a specific IP address and port number, you would run a command similar to the following:

dfx bootstrap --ip 192.168.47.1 --port 5353

The command displays output similar to the following:

binding to: V4(192.168.47.1:5353)
replica(s): \http://127.0.0.1:8080/api
Webserver started...

To use the default server address and port number but specify a custom location for static assets and longer timeout period, you might run a command similar to the following:

dfx bootstrap --root $HOME/ic-projects/assets --timeout 60

You can use CTRL-C to stop the bootstrap server.

dfx build

Use the dfx build command to compile your program into a WebAssembly module that can be deployed on the Internet Computer. You can use this command to compile all of the programs that are defined for a project in the project’s dfx.json configuration file.

If you are connected to the Internet Computer running locally or on a sub-network, this command registers canister identifiers for all of the programs in your project and generates a canister_manifest.json file that stores details about the compiled program canisters it registered on the network.

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 dfx build command looks for the source code to compile into a canister in the directory you have configured using the canisters section in the dfx.json configuration file.

Basic usage

dfx build [flag] [option]

Flags

You can use the following optional flags with the dfx build command.

Flag Description

--check

Builds canisters using a temporary, hard-coded, locally-defined canister identifier for testing that your program compiles without connecting to the Internet Computer network.

-h, --help

Displays usage information.

--skip-frontend

Skips building the canister frontend. Use this option when creating terminal-based programs or for testing functionality before creating front-end code.

-V, --version

Displays version information.

Options

You can specify the following option for the dfx build command.

Option Description

--network <network>

Specifies the Internet Computer network you want to connect to. You can use this option to override the network specified in the dfx.json configuration file.

Examples

You can use the dfx build command to build one or more WebAssembly modules from the programs specified in the dfx.json configuration file under the canisters key. For example, if your dfx.json configuration file defines one hello_world canister and one hello_world_assets canister, then running dfx build compiles two WebAssembly modules:

{
  "canisters": {
    "hello_world": {
      "main": "src/hello_world/main.mo",
      "type": "motoko"
    },
    "hello_world_assets": {
      "dependencies": [
        "hello_world"
      ],
      "frontend": {
        "entrypoint": "src/hello_world_assets/public/index.js"
      },
      "source": [
        "src/hello_world_assets/assets",
        "dist/hello_world_assets/"
      ],
      "type": "assets"
    }
  },
  "defaults": {
    "build": {
      "packtool": ""
    }
  },

  "dfx": "0.6.0",
  "networks": {
    "local": {
      "bind": "127.0.0.1:8000",
      "type": "ephemeral"
    },
    "tungsten": {
      "providers": [
        "https://gw.dfinity.network"
      ],
      "type": "persistent"
    }
  },
  "version": 1
}

Note that the file name and path to the programs on your file system must match the information specified in the dfx.json configuration file.

To build a canister without front-end code, you would run the following command:

dfx build --skip-frontend

To test whether a canister compiles without connecting to any Internet Computer network, you would run the following command:

dfx build --check

dfx cache

Use the dfx cache command with flags and subcommands to manage the dfx version cache.

Basic usage

dfx cache [subcommand] [flag]

Flags

You can use the following optional flags with the dfx cache command.

Flag Description

-h, --help

Displays usage information.

-V, --version

Displays version information.

Subcommands

Use the following subcommands to specify the operation you want to perform or to view usage information for a specific command.

Command Description

delete

Deletes the specified version of dfx from the local cache.

help

Displays usage information message for a specified subcommand.

install

Installs the specified version of dfx from the local cache.

list

Lists the versions of dfx currently installed and used in current projects.

show

Show the path of the cache used by this version of the dfx executable.

Examples

You can use the dfx cache command to display usage information for its subcommands. To view usage information for a specific subcommand, specify the subcommand and the --help flag. For example, to see usage information for dfx cache delete, you can run the following command:

dfx cache delete --help

dfx cache delete

Use the dfx cache delete command to delete a specified version of dfx from the version cache on the local computer.

Basic usage

dfx cache delete [version] [flag]

Flags

You can use the following optional flags with the dfx cache delete command.

Flag Description

-h, --help

Displays usage information.

-V, --version

Displays version information.

Arguments

You can specify the following argument for the dfx cache delete command.

Command Description

version

Specifies the version of dfx you to delete from the local cache.

Examples

You can use the dfx cache delete command to permanently delete versions of dfx that you no longer want to use. For example, you can run the following command to delete dfx version 0.5.2:

dfx cache delete 0.5.2

dfx cache install

Use the dfx cache install command to install dfx using the version currently found in the dfx cache.

Basic usage

dfx cache install [flag]

Flags

You can use the following optional flags with the dfx cache install command.

Flag Description

-h, --help

Displays usage information.

-V, --version

Displays version information.

Examples

You can use the dfx cache install command to force the installation of dfx from the version in the cache. For example, you can run the following command to install dfx:

+

dfx cache install

dfx cache list

Use the dfx cache list command to list the dfx versions you have currently installed and used in projects.

If you have multiple versions of dfx installed, the cache list displays an asterisk (*) to indicate the currently active version.

Basic usage

dfx cache list [flag]

Flags

You can use the following optional flags with the dfx cache list command.

Flag Description

-h, --help

Displays usage information.

-V, --version

Displays version information.

Examples

You can use the dfx cache list command to list the dfx versions you have currently installed and used in projects. For example, you can run the following command to list versions of dfx found in te cache:

dfx cache list

This command displays the list of dfx versions found similar to the following:

0.5.4 *
0.5.3
0.5.0

dfx cache show

Use the dfx cache show command to display the full path to the cache used by the dfx version you are currently using.

Basic usage

dfx cache show [flag]

Flags

You can use the following optional flags with the dfx cache show command.

Flag Description

-h, --help

Displays usage information.

-V, --version

Displays version information.

Examples

You can use the dfx cache show command to display the path to the cache used by the dfx version you are currently using:

dfx cache show

This command displays the path to the cache used by the dfx version you are currently using:

/Users/pubs/.cache/dfinity/versions/0.5.4

dfx canister

Use the dfx canister command with flags and subcommands to manage canister operations and interaction with the Internet Computer platform.

Basic usage

dfx canister [subcommand] [flag]

Flags

You can use the following optional flags with the dfx canister command.

Flag Description

-h, --help

Displays usage information.

-V, --version

Displays version information.

Options

You can specify the following option for the dfx canister command.

Option Description

--network <network>

Specifies the Internet Computer network you want to connect to. You can use this option to override the network specified in the dfx.json configuration file.

Subcommands

Use the following subcommands to specify the operation you want to perform or to view usage information for a specific command.

Command Description

call

Calls a specified method on a deployed canister.

create

Creates a new "empty" canister by registering a canister identifier on an Internet Computer network.

help

Displays usage information message for a specified subcommand.

id

Displays the identifier for a canister.

install

Installs compiled code as a canister on the replica.

request-status

Request the status of a call to a canister.

Examples

In most cases, you use dfx canister subcommands after you compile a program to manage the canister lifecycle and perform key tasks such as calling program functions.

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

Registering a canister identifier

To register unique canister identifiers for a project, you can run the following command:

dfx canister create --all

Overriding the default network

If you want to send a dfx canister subcommand to a specific network provider address and port number without changing the settings in your dfx.json configuration file, you can explicitly specify the network using the --network option.

For example, you can specify a remote Internet Computer network by running a command similar to the following:

dfx canister --network \http://192.168.3.1:5678 call counter get

Note that you must specify the network parameter before the canister operation (call), canister name (counter), and function (get).

dfx canister call

Use the dfx canister call command to call a specified method on a deployed canister.

Basic usage

dfx canister call [option] canister_name method_name [argument] [flag]

Flags

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 replica.

-h, –help

Displays usage information.

–query

Enables you to send a query request to a deployed canister. For best performance and network efficiency, 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.

–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.

Options

You can use the following options with the dfx canister call command.

Option Description

--output <output>

Specifies the output format to use when displaying a method’s return result. The valid values are idl and raw.

--type <type>

Specifies the data type for the argument when making the call using an argument. The valid values are idl and raw.

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

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 type using the --type option if you pass an argument to the canister. The default type is idl. For information about the interface description types that you can use for arguments, see Interface description syntax for arguments. You can use raw as the argument type if you want to pass raw bytes to a canister.

Interface description syntax for arguments

The --type idl option specifies a special syntax, which is different from Motoko, for representing argument values. The syntax provides a language-agnostic way to communicate with canisters using different languages and tools. Specifically, the Candid interface description language (IDL) enables you to use the same syntax to specify input argument values and display return values from canister methods, regardless of whether you are using the dfx command-line interface, JavaScript, Motoko, or another supported language or tool.

The IDL format accepts multiple argument values separated by commas (,) and wrapped inside parentheses. For example, specifying (42, true) represents two argument values, where the first argument is the number 42 and the second argument is a boolean value of true.

The IDL supports the following value forms:

  • Unit value (null).

  • Boolean values (true, false).

  • Integers (…​, -2, -1, 0, +1, +2, …​).

  • Natural numbers (0, 1, 2, …​) or (0x0, 0x01, …​, 0xfff, …​)

  • Text values "string of unicode characters".

  • Optional values (none, opt 42, opt opt "optional text", …​).

  • Vector of values (vec { 1; 2; 3; }, …​).

  • Record/struct with named labels and values (record { label = opt 42; 3 = "numbered label" }, …​).

  • Variant/enum with a single named label and value (variant { ok = "ok result value" }, variant { Err = null }, …​).

  • Values with type annotations (42 : nat, 42 : int, …​).

The IDL interprets numbers with plus signs—for example. +42—as integers and numbers without plus signs—for example, 42—as natural numbers. However, since Nat is a subtype of Int in Motoko, you can always write 42 without the plus sign for functions that expect integers.

For compound types, such as record and variant, labels can be either natural numbers or strings. However, the string label is only present for better readability. Behind the scenes, the string label is converted into a natural number using a fixed hash function. If the canister method returns a record or variant type, the field labels will always be natural numbers.

For a more detailed discussion of the interface description language, see the Candid specification and Candid Rust crate documentation.

Examples

You can use the dfx canister call command to invoke specific methods—with or without arguments—after you have deployed the canister on the network 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 replica 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.

dfx canister create

Use the dfx canister create command to register one or more canister identifiers without compiled code on the Internet Computer network. You must be connected to an Internet Computer network running locally or on a sub-network that you can access 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 [flag] [--all | canister_name]

Flags

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.

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

You can use the dfx canister create command to register canister identifiers without first compiling any code. For example, if you want to create the canister identifier for the project my_counter before writing the program, you can run the following command:

dfx canister create my_counter

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.

Basic usage

dfx canister id [flag] canister_name

Flags

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

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

You can use the dfx canister id command to display the canister identifier for a specific canister name.

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 install

Use the dfx canister install command to install compiled code as a canister on the Internet Computer network running locally or on a sub-network that you can access.

Basic usage

dfx canister install [flag] [option] [--all | canister_name]

Flags

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 replica.

-h, --help

Displays usage information.

-V, --version

Displays version information.

Options

You can use the following options with the dfx canister install command.

Option Description

-c, --compute-allocation <compute-allocation>

Defines a compute allocation—essentially the equivalent of setting CPU allocation—for canister execution.

-m, --mode <mode>

Specifies whether you want to install, reinstall, or upgrade canisters. For more information about installation modes and canister management, see Managing canisters.

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 WebAssembly you have compiled using the dfx build command as a canister on the network. 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 canister and a hello_world_assets canister but only want to deploy the hello_world canister, you can deploy just that the canister by running the following command:

dfx canister install hello_world

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 --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 network provider

If you want to deploy a canister on a specific Internet Computer network without changing the settings in your dfx.json configuration file, you can explicitly specify the network you want to connect to by using the +--network option.

For example, you can specify a remote network by running a command similar to the following:

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.

Allocating message processing

The --compute-allocation options 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 install --all --compute-allocation 50

With this setting, all of the canisters in the current projects are assigned a 50% allocation. When canisters in the project receive input messages to process, the messages are scheduled for execution. Over 100 execution cycles, 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.

In a development environment, you might use this option for testing purposes if you have applications that require multiple canisters.

dfx canister request-status

Use the dfx canister request-status to request the status of a specified 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 request_id

Flags

You can use the following optional flags with the dfx canister request-status command.

Flag Description

-h, --help

Displays usage information.

-V, --version

Displays version information.

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.

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

This command displays an error message if the request identifier is invalid or refused by the canister.

dfx config

Use the dfx config command to view or configure settings in the configuration file for a current project. 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 config [config_path] [value] [flag]

Flags

You can use the following optional flags with the dfx config command.

Flag Description

-h, --help

Displays usage information.

-V, --version

Displays version information.

Options

You can use the following option with the dfx config command.

Option Description

--format

Specifies the format of the configuration file output. By default, the file is displayed using JSON format. The valid values are json and text.

Arguments

You can specify the following arguments for the dfx config command.

Argument Description

config_path

Specifies the name of the configuration option that you want to set or read. You must specify the configuration file option using its period-delineated path to set or read the specific option you want to change or view. If you don’t specify the path to a specific configuration option, the command displays the full configuration file.

value

Specifies the new value for the option you are changing. If you don’t specify a value, the command returns the current value for the option from the configuration file.

Examples

You can use the dfx config command to change configuration settings such as the location of the default output directory or the name of your main program file.

For example, to change the default build output directory from canisters to staging, you can run the following command:

dfx config defaults.build.output "staging/"

To view the current value for a configuration setting, you can specify the path to the setting in the configuration file without specifying a value. For example:

dfx config defaults.build.output

The command returns the current value for the configuration option:

"staging/"

Similarly, you can change the name of the main source file or the port number for the local network replica by running commands similar to the following:

dfx config canisters.hello.main "src/hello_world/hello-main.mo"
dfx config networks.local.bind 127.0.0.1:5050

You can also verify your configuration changes by viewing the dfx.json configuration file after running the dfx config command.

dfx help

Use this command to view usage information for the dfx parent command or for any specified subcommand.

Basic usage

dfx help [subcommand]

Arguments

You can specify any dfx subcommand as an argument to view usage information for that subcommand using the dfx help command.

Argument Description

subcommand

Specifies the subcommand usage information you want to display.

Examples

To display the usage information for dfx, run the following command:

dfx help

To display the usage information for dfx bew, run the following command:

dfx help new

dfx new

Use the dfx new command to create a new project for the Internet Computer platform. This command creates a default project structure with template files that you can modify to suit your application. You must specify the name of the project to you want to create.

You can use the --dry-run option to preview the directories and files to be created without adding them to the file system.

Basic usage

dfx new _project_name_ [flag]

Flag

You can use the following optional flags with the dfx new command:

Flag Description

--dry-run

Generates a preview the directories and files to be created for a new project without adding them to the file system.

--frontend

Installs the template frontend code for the default project canister. The default value for the flag is true if node.js is currently installed on your local computer. If node.js is not currently installed, you can set this flag to true to attempt to install node.js and the template file when creating the project or you can set the flag to false to skip the installation of template frontend code entirely.

-h, --help

Displays usage information.

-V, --version

Displays version information.

Arguments

You can specify the following argument for the dfx new command.

Argument Description

project_name

Specifies the name of the project to create. This argument is required.

Examples

You can use dfx new to create a new project named my_social_network by running the following command:

dfx new my_social_network

The command creates a new project, including a default project directory structure under the new project name and a Git repository for your project.

If you want to preview the directories and files to be created without adding them to the file system, you can run the following command:

dfx new my_social_network --dry-run

dfx ping

Use the dfx ping command to check connectivity between a local computer and an Internet Computer network provider. This command enables you to verify that you can connect to a specific Internet Computer network and that the remote network services are running.

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 ping [provider] [flag]

Flags

You can use the following optional flags with the dfx ping command.

Flag Description

-h, --help

Displays usage information.

-V, --version

Displays version information.

Arguments

You can specify the following argument for the dfx ping command.

Argument Description

provider

Specifies the network provider URL that you want to use.

Examples

You can use the dfx ping command to check whether the Internet Computer is currently available at a specific network address by running a command similar to the following:

dfx ping https://testgw.dfinity.network

If the Internet Computer is running on the specified network provider address, the command returns output similar to the following:

{
  "ic_api_version": "0.8"
}

dfx replica

Use the dfx replica command to start a Internet Computer replica process (without a web server) locally. This command enables you to deploy canisters locally to simulate network deployment and to test your programs during development.

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 replica [option] [flag]

Flags

You can use the following optional flags with the dfx replica command.

Flag Description

-h, --help

Displays usage information.

-V, --version

Displays version information.

Options

You can use the following option with the dfx replica command.

Option Description

--port port

Specifies the port the local replica should listen to.

Examples

You can start the Internet Computer replica by running the following command:

dfx replica

dfx start

Use the dfx start command to start a local Internet Computer replica process and web server processes for the current project. This command enables you to deploy canisters to the local Internet Computer network to test your programs during development.

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 start [option] [flag]

Flags

You can use the following optional flags with the dfx start command.

Flag Description

--background

Starts the Internet Computer replica and web server processes in the background and waits for a reply before returning to the shell.

--clean

Starts the Internet Computer replica and web server processes in a clean state by removing checkpoints from your project cache. You can use this flag to set your project cache to a new state when troubleshooting or debugging.

-h, --help

Displays usage information.

-V, --version

Displays version information.

Options

You can use the following option with the dfx start command.

Option Description

--host host

Specifies the host name and port number to bind the frontend to.

Examples

You can start the Internet Computer replica and web server processes in the current shell by running the following command:

dfx start

If you start the Internet Computer in the current shell, you need to open a new terminal shell to run additional commands. Alternatively, you can start the Internet Computer in the background by running the following command:

dfx start --background

If you run the Internet Computer in the background, however, be sure to stop the network before uninstalling or reinstalling the dfx execution environment by running the following command:

dfx stop

You can view the current process identifier (pid) for the Internet Computer process started by dfx by running the following command:

more .dfx/pid

dfx stop

Use the dfx stop command to stop the Internet Computer processes that you currently have running on your local computer. In most cases, you run the Internet Computer locally so that you can deploy canisters and test your programs during development. To simulate an external Internet Computer connection, these processes run continuously either in a terminal shell where you started them or the in the background until you stop or kill them.

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 stop [flag]

Flags

You can use the following optional flags with the dfx stop command.

Flag Description

-h, --help

Displays usage information.

-V, --version

Displays version information.

Examples

You can stop the Internet Computer network processes that are running in the background by changing to a project directory then running the following command:

dfx stop

If the local Internet Computer network is running in a current shell rather than in the background, open a new terminal shell, change to a project directory, then run the dfx stop command.

The current process identifier (pid) for the Internet Computer process started by dfx is recorded in the .dfx/pid file. You can view the process identifier before running the dfx stop command by running the following command:

more .dfx/pid

This command displays a process identifier similar to the following:

1896

dfx upgrade

Use the dfx upgrade command to upgrade the DFINITY Canister SDK components running on your local computer. This command checks the version of the DFINITY Canister SDK that you have currently installed, then upgrades to the latest version available if an older version is detected.

Basic usage

dfx upgrade [flag]

Flags

You can use the following optional flags with the dfx upgrade command.

Flag Description

-h, --help

Displays usage information.

-V, --version

Displays version information.

Examples

You can upgrade the version of the DFINITY Canister SDK that you have currently installed by running the following command:

dfx upgrade

This command checks the version of dfx you have currently installed and the latest version available published on the DFINITY Canister SDK website in a manifest file. If a newer version of dfx is available, the command automatically downloads and installs the latest version.

Current version: 0.5.7
Fetching manifest \https://sdk.dfinity.org/manifest.json
Already up to date