Legacy Starknet CLI reference

The Starknet CLI is deprecated. Instead, use StarkLi CLI.

Basic command line syntax

To enter a Starknet command, use the following syntax:

$ starknet <command> <options>

Where:

<command> represents a single command that executes an operation on Starknet.

<options> represents zero or more command line options, each of which modifies the operation of the command.

Setting the Starknet network environment

You need to set your Starknet network environment to use either testnet or Mainnet.

You can set the environment using either a command-line option or an environment variable.

Possible values are:

sepolia

Sets the Starknet network to testnet

mainnet

Sets the Starknet network to Mainnet

Setting the network environment using a command-line option

When you enter any command, include the --network option. For example to use Mainnet, enter a command as follows:

$ starknet <command> --network alpha-mainnet <options>

You can place the --network option before or after any other option.
Setting the network environment using an environment variable

Set the STARKNET_NETWORK environment variable as follows:

$ export STARKNET_NETWORK=<starknet_network>

For example, to use testnet, enter the following command:

$ export STARKNET_NETWORK=sepolia

Setting custom endpoints

When working with the CLI, you can manually set the endpoints for the gateways that enable you to interact with Starknet, by including the following options:

--feeder_gateway_url

Sets the custom endpoint for read commands.

--gateway_url

Sets the custom endpoint for write commands.

The following are the endpoints for Starknet testnet and Mainnet:

Example: Setting a custom read endpoint

The following command returns the ABI using the Mainnet feeder gateway.

$ starknet get_code --feeder_gateway_url https://alpha-mainnet.starknet.io/feeder_gateway/ <options>
Example: Setting a custom write endpoint

The following command sends a transaction to the Starknet sequencer using the Mainnet gateway.

$ starknet invoke --gateway_url https://alpha-mainnet.starknet.io/gateway/ <options>

starknet call

starknet call
  --address <contract_address>
  --abi <contract_abi>
  --function <function_name>
  --inputs <arguments>
  --block_hash <block_hash>
  --block_number <block_number>
  --signature <signature_information>
  --wallet <wallet_name>
  --nonce <nonce>

Calls a Starknet contract without affecting the state, accepts the following arguments:

  • contract_address* - address of the contract being called

  • contract_abi* - a path to a JSON file that contains the abi of the contract being called

  • function_name* - name of the function which is called

  • arguments* - inputs to the function being called, represented by a list of space-delimited values

  • block_hash - the hash of the block used as the context for the call operation. If this argument is omitted, the latest block is used

  • block_number - same as block_hash, but specifies the context block by number or tag

  • signature_information - list of field elements as described here

  • wallet_name - the name of the desired wallet, use deploy_account to set-up new accounts in the CLI

  • nonce - account nonce, only relevant if the call is going through an account

Block Tag

A block context can be specified via the latest or pending tags, where the former refers to the latest accepted on L2 block and the latter refers to the pending block.

starknet declare

starknet declare
--contract <contract_class>

Declares a new contract class on Starknet, accepts the following argument:

  • contract_class - path to a JSON file containing the contract’s compiled code

starknet deploy

starknet deploy
  --salt <salt>
  --contract <contract_definition>
  --inputs <constructor_inputs>
  --token <token>

Deploys a new contract, accepts the following arguments:

  • salt - a seed that is used in the computation of the contract’s address (if not specified, the sequencer will choose a random string)

  • contract_definition* - path to a JSON file containing the contract’s bytecode and abi (can be obtained by executing starknet-compile)

  • constructor_inputs* - the arguments given to the contract’s constructor, represented by a list of space-delimited values

  • token - a token allowing contract deployment (can be obtained by applying here). Only used in the Alpha stages and will be deprecated in the future

The deploy token is a temporary measure which will be deprecated when fees are incorporated in the system. Only relevant for Mainnet.

starknet deploy_account

starknet deploy_account
  --wallet <wallet_provider>
  --account <account_name>

Deploys an account contract, accepts the following arguments:

  • account_name - the name given to the account, used for managing multiple accounts from the CLI (if not specified, the name __default__ is used.

  • wallet_provider* - the path to module which manages the account (responsible for key generation, signing, etc.)

Today, the Starknet CLI only works with the OpenZeppelin account contract. The CLI uses this specific wallet provider. To use this provider, either set up the following environment variable or pass the same value directly to the wallet_provider parameter:

$ export STARKNET_WALLET=starkware.starknet.wallets.open_zeppelin.OpenZeppelinAccount

Using the built-in wallet providers that are part of the cairo-lang package (starkware.starknet.wallets…​) is not secure (for example, the private key may be kept not encrypted and without backup in your home directory). You should only use them if you’re not overly concerned with losing access to your accounts (for example, for testing purposes).

starknet estimate_fee

starknet estimate_fee
    --address <contract_address>
    --abi <contract_abi>
    --function <function_name>
    --inputs <arguments>

Returns the fee estimation for a given contract call. Accepts the following arguments:

  • address* - the address of the contract being called

  • contract_abi* - a path to a JSON file that contains the abi of the contract being called

  • function_name*- the name of the function being called

  • arguments* - inputs to the function being called, represented by a list of space-delimited values`

starknet estimate_message_fee

starknet estimate_message_fee
    --from_address <sender_address>
    --to_address <contract_address>
    --function <function_name>
    --inputs <arguments>

Returns the fee estimation for a given L1 handler application. Accepts the following arguments:

  • from_address* - the L1 address of the sender

  • to_address* - the L2 address of the recipient

  • contract_abi* - a path to a JSON file containing the abi of the receiving contract on L2

  • function_name*- the name of the desired L1 handler

  • arguments* - inputs to the called handler, represented by a list of space-delimited values

starknet get_block

starknet get_block
  --hash <block_hash>
  --number <block_number>

Returns the requested block, exactly one of the following arguments must be given:

  • block_hash - hash of the requested block

  • block_number - number or tag of the requested block

starknet get_code

starknet get_code
  --contract_address <contact_address>
  --block_hash <block_hash>
  --block_number <block_number>

Returns the ABI and the byte code of the requested contract, accepts the following arguments:

  • contact_address* - address of the requested contract

  • block_hash - the hash of the block used as the context for the operation. If this argument is omitted, the latest block is used

  • block_number - same as block_hash, but specifies the context block by number or tag

starknet get_storage_at

starknet get_storage_at
  --contract_address <contract_address>
  --key <key>
  --block_hash <block_hash>
  --block_number <block_number>

Queries a contract’s storage at a specific key, accepts the following arguments:

  • contract_address *- address of the requested contract

  • key* - the requested key from the given contract’s storage

  • block_hash - the hash of the block relative to which the storage will be provided. In case this argument is not given, the latest block is used

  • block_number - same as block_hash, but specifies the context block by number or tag

starknet get_transaction

starknet get_transaction --hash <transaction_hash>

Returns the requested transaction, expects the following argument:

  • transaction_hash* - hash of the requested transaction

starknet get_transaction_receipt

starknet get_transaction_receipt --hash <transaction_hash>

Returns the receipt associated with the transaction, expects the following argument:

  • transaction_hash* - hash of the requested transaction starknet invoke starknet tx_status

starknet invoke

starknet invoke
  --address <contract_address>
  --abi <contract_abi>
  --function <function_name>
  --inputs <arguments>
  --signature <signature_information>
  --wallet <wallet_name>
  --nonce <nonce>

Sends a transaction to the Starknet sequencer, accepts the following arguments:

  • address* - the address of the contract being called

  • contract_abi* - a path to a JSON file that contains the abi of the contract being called

  • function_name*- the name of the function being called

  • arguments* - inputs to the function being called, represented by a list of space-delimited values

  • signature_information - list of field elements as described here

  • wallet_name - the name of the desired wallet, use deploy_account to set-up new accounts in the CLI.

  • nonce - account nonce, only relevant if the call is going through an account

Today, interaction with Starknet may be done either via account or by a direct call. The signature argument can only be provided in the case of a direct call, since otherwise providing the signature is the responsibility of the account module. To use an account you must specify wallet_name, otherwise a direct call will be used (you may also explicitly perform a direct call by adding --no_wallet to the command). Note that in the future direct calls will be deprecated and the only way to interact with the system would be through accounts.

starknet tx_status

starknet tx_status
  --hash <transaction_hash>
  --contract <contract_definition>
  --error_message

Returns the transaction status, accepts the following arguments:

  • transaction_hash* - hash of the requested transaction

  • contract_definition - path to a JSON file containing the compiled contract to which the transaction was addressed. If supplied, the debug information from the compiled contract will be used to add error locations.

  • error_message - if specified, only the error message will be returned (or empty response in case the transaction was successful)

The possible statuses of a transaction are:

  • NOT_RECEIVED

  • RECEIVED

  • PENDING

  • REJECTED

  • ACCEPTED_ON_L2

  • ACCEPTED_ON_L1

For more information, see Transaction lifecycle.