Shopify CLI commands for apps
This reference lists the commands that you can use to build apps with Shopify CLI.
Command overview
Anchor link to section titled "Command overview"Topic | Command | Description |
---|---|---|
app | dev | Builds the app and lets you preview it on a development store or Plus sandbox store. |
info | Displays information about your app. | |
generate extension | Creates a new app extension for your app. | |
function build | Compiles the function in your current directory to WebAssembly (Wasm) for testing purposes. | |
function run | Runs the function from your current directory for testing purposes. | |
function schema | Generates the latest GraphQL schema for a function in your app. | |
function typegen | Creates GraphQL types based on your input query for a function written in JavaScript. | |
build | Builds the app, including extensions. | |
config link | Pulls app configuration from the Partner Dashboard and creates or overwrites a configuration file. | |
config push | Pushes your app configuration to Shopify. | |
config use | Sets a particular configuration file as your project's default when you run app-related CLI commands. | |
deploy | Builds the app and deploys all of the extensions in your app to Shopify. | |
release | Releases an existing app version. | |
versions list | Lists the deployed app versions. | |
env | Stores or displays environment variables required for app deployment. | |
update-url | Updates the app URL and allowed redirection URLs for your app. | |
config | autocorrect | Enables or disables command autocorrection. |
auth | logout | Logs you out of your Shopify Partner account. |
webhook | trigger | Triggers the delivery of a sample event topic payload to a designated address. |
none | help | Lists the available commands and describes what they do. |
version | Lists the version of Shopify CLI included in the project. | |
upgrade | Upgrades the @shopify/cli and @shopify/app packages to their latest versions. |
|
search | Starts a search on Shopify.dev. |
Command syntax
Anchor link to section titled "Command syntax"Shopify CLI commands should only be run in a project where Shopify CLI is installed.
You can run all Shopify CLI commands using the run
command:
You can also run some commands as scripts, which use an abbreviated syntax:
Some package managers require a separator to pass flags to the script:
Builds the app and lets you preview it on a development store or Plus sandbox store.
To preview your app on a development store or Plus sandbox store, Shopify CLI walks you through the following steps. If you've run dev
before, then your settings are saved and some of these steps are skipped:
- Associating your project with an app associated with your Partner account or organization, or creating a new app.
- Selecting a development store or Plus sandbox store to use for testing. If you have only one store, then it's selected automatically.
- Installing your app on the store using the provided install link.
Creating a tunnel between your local environment and the store using Cloudflare.
You can use your own tunneling software instead, by passing your tunnel URL with the
--tunnel-url
flag.Updating the app URLs that are set in the Partner Dashboard.
To avoid overwriting any URLs that are already set, select the No, never option. If you select this option, then you're provided with URLs that you can manually add in the Partner Dashboard so you can preview your app.
Enabling development store preview for extensions.
Building and serving your app and app extensions.
If you're using the PHP or Ruby app template, then you need to complete the following steps before you can preview your app for the first time:
- PHP: Set up your Laravel app
- Ruby: Set up your Rails app
Flag | Alias | Description |
---|---|---|
--tunnel-url |
The URL of a tunnel that you've started using your own local tunneling software. Shopify recommends Cloudflare tunnel for use with Shopify CLI. Expected format: https://my-tunnel-url:port |
|
--store <store> |
-s <store> |
The development store or Plus sandbox store that you want to use to preview your app. The --store flag accepts the following inputs:
|
--config <name> |
The name of the config to use. | |
--client-id <id> |
The client ID of your app. Use this flag to specify the app that you want connect your project with. This flag replaces the deprecated --api-key flag. |
|
--no-update |
Skip the prompt to update the app URLs that are set in the Partner Dashboard. Your URLs won't be updated. | |
--path <path> |
The path to your app directory. | |
--skip-dependencies-installation |
Skip checking and installing missing dependencies for your app. | |
--reset |
Reset all of your dev settings and send an uninstall request for the store to the default webhook endpoint (/api/webhooks ), or the endpoint defined in shopify.web.toml. |
|
--verbose |
Provide more detailed output in the logs. | |
--no-color |
Disables color output in the logs. | |
--checkout-cart-url |
A partial link with a product variant ID and quantity to be used to create a test checkout for checkout UI extensions. If the flag isn't passed, then Shopify CLI auto-populates this value. To test with a specific product variant ID and quantity, you can provide the flag as --checkout-cart-url "/cart/12345:1" , where 12345 is the product variant ID and :1 is the quantity. |
|
--subscription-product-url |
A partial link with a product ID. Use this flag to specify the product to use when testing a purchase option extension. If the flag isn't passed, then Shopify CLI auto-populates this value. To test with a specific product ID, you can provide the flag as --subscription-product-url "/products/12345" , where 12345 is the product ID. |
|
--theme-app-extension-port <port> |
The local port to be used to test a theme app extension. | |
--theme <ID or name> |
-t |
The ID or name of the theme to be used to test a theme app extension. If no theme is specified, then the command will use Dawn, Shopify's example theme, when testing your theme app extension. |
Displays information about your app.
The information returned includes the following:
- The app and development store or Plus sandbox store that's used when you run the
dev
command. You can reset these configurations usingdev --reset
. - The structure of your app project.
- The access scopes your app has requested.
- System information, including the package manager and version of Shopify CLI used in the project.
Flag | Description |
---|---|
--path <path> |
The path to your app directory. |
--config <name> |
The name of the config to use. |
--verbose |
Provide more detailed output in the logs. |
--no-color |
Disables color output in the logs. |
--json |
Output the app info in JSON format. |
generate extension
Anchor link to section titled "generate extension"Generates a new app extension. For a list of app extensions that you can generate using this command, refer to Supported extensions.
Each new app extension is created in a folder under extensions/
. To learn more about the extensions file structure, refer to App structure and the documentation for your extension.
generate extension flags
Anchor link to section titled "generate extension flags"Flag | Alias | Description |
---|---|---|
--name <name> |
-n <name> |
The name of your extension. |
--template <template> |
-t <template> |
The extension template. Refer to supported extensions. |
--path <path> |
The path to your app directory. | |
--config <name> |
The name of the config to use. | |
--verbose |
Provides more detailed output in the logs. | |
--no-color |
Disables color output in the logs. | |
--flavor |
Choose the language of the template that you want to start with. The languages that are available depend on the extension you're generating. For example:
|
Supported extensions
Anchor link to section titled "Supported extensions"Extension | type value in the TOML file |
--template flag value in the generate command |
---|---|---|
Checkout UI Developer preview |
ui_extension |
checkout_ui |
Admin action | ui_extension |
admin_action |
Admin block Developer preview |
ui_extension |
admin_block |
Product configuration | ui_extension |
product_configuration |
Shopify Flow trigger | flow_trigger |
flow_trigger |
Shopify Flow action | flow_action |
flow_action |
Order discount | order_discounts |
order_discounts |
Product discount | product_discounts |
product_discounts |
Shipping discount Developer preview |
shipping_discounts |
shipping_discounts |
Delivery customization | delivery_customization |
delivery_customization |
Payment customization | payment_customization |
payment_customization |
Order routing location rule Beta |
order_routing_location_rule |
order_routing_location_rule |
Cart and checkout validation | cart_checkout_validation |
cart_checkout_validation |
Cart transform | cart_transform |
cart_transform |
Fulfillment constraints | fulfillment_constraints |
fulfillment_constraints |
Post-purchase UI Beta |
post_purchase_ui |
post_purchase_ui |
Product subscription | subscription_ui |
subscription_ui |
Web pixel | web_pixel |
web_pixel |
Shopify POS UI | pos_ui_extension |
pos_ui |
Theme app extensions | theme_app_extension |
theme_app_extension |
function build
Anchor link to section titled "function build"Compiles the function in your current directory to WebAssembly (Wasm) for testing purposes.
function build flags
Anchor link to section titled "function build flags"Flag | Description |
---|---|
--path <path> |
The path to your function directory. |
--config <name> |
The name of the config to use. |
--verbose |
Increase the verbosity of the logs. |
--no-color |
Disables color output in the logs. |
function run
Anchor link to section titled "function run"Runs the function from your current directory for testing purposes. To learn how you can monitor and debug functions when errors occur, refer to Shopify Functions error handling.
function run flags
Anchor link to section titled "function run flags"Flag | Alias | Description |
---|---|---|
--json |
-j |
Output the function result in JSON format. |
--path <path> |
The path to your function directory. | |
--config <name> |
The name of the config to use. | |
--verbose |
Increase the verbosity of the logs. | |
--no-color |
Disables color output in the logs. |
function schema
Anchor link to section titled "function schema"Generates the latest GraphQL schema for a function in your app. Run this command from the function directory.
This command uses the API type and version of your function, as defined in your extension TOML file, to generate the latest GraphQL schema. The schema is written to the schema.graphql
file.
function schema flags
Anchor link to section titled "function schema flags"Flag | Description |
---|---|
--client-id |
The client ID of your app. This flag replaces the deprecated --api-key flag. |
--path <path> |
The path to your function directory. |
--config <name> |
The name of the config to use. |
--stdout |
Output the schema to STDOUT instead of schema.graphql . |
--verbose |
Increase the verbosity of the logs. |
--no-color |
Disables color output in the logs. |
function typegen
Anchor link to section titled "function typegen"Creates GraphQL types based on your input query for a function written in JavaScript.
function typegen flags
Anchor link to section titled "function typegen flags"Flag | Description |
---|---|
--path <path> |
The path to your function directory. |
--config <name> |
The name of the config to use. |
--verbose |
Increase the verbosity of the logs. |
--no-color |
Disables color output in the logs. |
config link
Anchor link to section titled "config link"Pulls app configuration from the Partner Dashboard and creates or overwrites a configuration file. You can create a new app with this command to start with a default configuration file.
This command presents you with a prompt with the following steps:
- Which Partner organization is this work for?
- This prompt shows only if the account you are logged into has more than one organization.
- Create this project as a new app on Shopify?
- Choosing yes will create a new app in your Partner Dashboard with the default configuration
- Choosing no will prompt you to choose from a list of all the apps in your organization
- Configuration file name
- Enter the name for this configuration file. The
shopify.app.{config-name}.toml
file will be created. If it already exists, you will be prompted to confirm overwriting.
- Enter the name for this configuration file. The
For more information on the format of the created TOML configuration file, refer to the App configuration page.
Sets default configuration when you run app-related CLI commands. If you omit the config-name
parameter, then you'll be prompted to choose from the configuration files in your project.
config push
Anchor link to section titled "config push"Pushes your default app configuration to Shopify. You can specify a different configuration file with the --config
flag. This overwrites the settings for the app specified in the configuration file in your Partner Dashboard.
config push flags
Anchor link to section titled "config push flags"Flag | Description |
---|---|
--config <config> |
The name of the config to push. |
Builds the app, including extensions.
This command executes the build script specified in the element's TOML file. You can specify a custom script in the file. To learn about configuration files in Shopify apps, refer to App configuration.
If you're building a theme app extension, then running the build
command runs Theme Check against your extension to ensure that it's valid.
build flags
Anchor link to section titled "build flags"Flag | Description |
---|---|
--client-id |
Specify the client ID to use when building the app. This client ID is set as an environment variable, which is used by App Bridge. This flag is only required when building your app for production. This flag replaces the deprecated --api-key flag. |
--skip-dependencies-installation |
Skip checking and installing missing dependencies for your app. |
--path <path> |
The path to your app directory. |
--config <name> |
The name of the config to use. |
--verbose |
Increase the verbosity of the logs. |
--no-color |
Disables color output in the logs. |
Builds the app and deploys app extensions.
When you run this command, Shopify CLI creates an app version that contains a snapshot of all of your app extensions, including the app extensions that you manage in the Partner Dashboard, and releases the app version to users.
This command doesn't deploy your web app. When you're ready to deploy your app, you need to deploy these components to your own hosting solution. Learn more about deploying your web app.
deploy flags
Anchor link to section titled "deploy flags"Flag | Alias | Description |
---|---|---|
--version <version> |
Associates a name with the app version. If a version name isn't provided, then an auto-generated name is used. | |
--message <message> |
Associates a message with the app version. This is for internal use only and won't be available externally. | |
--source-control-url <url> |
Associates a URL with the app version. | |
--no-release |
Creates an app version but doesn't release it to users. The app version can later be released manually. | |
--config <name> |
Identifies the config to use by name. | |
--client-id <id> |
Specifies the client ID of your app. This flag replaces the deprecated --api-key flag. |
|
--reset |
Resets all of your deploy settings. |
|
--path <path> |
Specifies the path to your app directory. | |
--verbose |
Provides more detailed output in the logs. | |
--no-color |
Disables color output in the logs. | |
--force |
-f |
Skips the deploy summary confirmation prompt. |
Releases an existing app version. Pass the name of the version that you want to release using the --version
flag.
release flags
Anchor link to section titled "release flags"Flag | Description |
---|---|
--version <version> |
Required. The name of the app version that you want to release. |
--client-id <id> |
The client ID of your app. This flag replaces the deprecated --api-key flag. |
--reset |
Reset all of your release settings. |
--path <path> |
The path to your app directory. |
--config <name> |
The name of the config to use. |
--verbose |
Provide more detailed output in the logs. |
--no-color |
Disables color output in the logs. |
versions list
Anchor link to section titled "versions list"Lists the deployed app versions. An app version is a snapshot of your app extensions.
versions list flags
Anchor link to section titled "versions list flags"Flag | Description |
---|---|
--path <path> |
The path to your app directory. |
--config <name> |
The name of the config to use. |
--verbose |
Provide more detailed output in the logs. |
--no-color |
Disables color output in the logs. |
--client-id <id> |
The client ID of your app. This flag replaces the deprecated --api-key flag. |
Creates or updates an .env
files that contains app and app extension environment variables.
When an existing .env
file is updated, changes to the variables are displayed in the terminal output. Existing variables and commented variables are preserved.
env pull flags
Anchor link to section titled "env pull flags"Flag | Description |
---|---|
--env-file |
Specify the file where environment variables are saved. If the file doesn't exist, then it will be created. |
--path <path> |
The path to your app directory. |
--config <name> |
The name of the config to use. |
--verbose |
Provide more detailed output in the logs. |
--no-color |
Disables color output in the logs. |
Displays environment variables that can be used to deploy apps and app extensions.
env show flags
Anchor link to section titled "env show flags"Flag | Description |
---|---|
--path <path> |
The path to your app directory. |
--config <name> |
The name of the config to use. |
--verbose |
Provide more detailed output in the logs. |
--no-color |
Disables color output in the logs. |
Updates the app URL and allowed redirection URLs for your app. When you specify URLs using this command, the current URLs are overwritten.
Your current app URLs are provided as placeholder responses. To keep either your app URL or redirect URLs the same, submit the placeholder content. Alternatively, use the --app-url
or --redirect-urls
flag to update only one of these settings.
update-url flags
Anchor link to section titled "update-url flags"Flag | Description |
---|---|
--client-id |
The client ID of your app. Use this flag to specify the app that you want to update. This flag replaces the deprecated --api-key flag. |
--app-url |
The new app URL for the app. |
--redirect-urls |
A comma-separated list of the new allowed redirection URL or URLs for the app. |
--path <path> |
The path to your app directory. |
--config <name> |
The name of the config to use. |
--verbose |
Provide more detailed output in the logs. |
--no-color |
Disables color output in the logs. |
config autocorrect
Anchor link to section titled "config autocorrect"Enables or disables command autocorrection. By default, autocorrect is off.
When autocorrection is enabled, Shopify CLI automatically runs a corrected version of your command if a correction is available.
When autocorrection is disabled, you need to confirm that you want to run corrections for mistyped commands.
Command | Description |
---|---|
on |
Enable autocorrect. |
off |
Disable autocorrect. |
status |
Check whether autocorrect is enabled or disabled. |
auth logout
Anchor link to section titled "auth logout"Logs you out of the Shopify account or Partner account and store.
webhook trigger
Anchor link to section titled "webhook trigger"Triggers the delivery of a sample Admin API event topic payload to a designated address.
You should use this command to experiment with webhooks, to initially test your webhook configuration, or for unit testing. However, to test your webhook configuration from end to end, you should always trigger webhooks by performing the related action in Shopify.
Because most webhook deliveries use remote endpoints, you can trigger the command from any directory where you can use Shopify CLI, and send the webhook to any of the supported endpoint types. For example, you can run the command from your app's local directory, but send the webhook to a staging environment endpoint.
To learn more about using webhooks in a Shopify app, refer to Webhooks overview.
Limitations
Anchor link to section titled "Limitations"- Webhooks triggered using this method always have the same payload, so they can't be used to test scenarios that differ based on the payload contents.
- Webhooks triggered using this method aren't retried when they fail.
- Trigger requests are rate-limited using the Partner API rate limit.
- You can't use this method to validate your API webhook subscriptions.
webhook trigger flags
Anchor link to section titled "webhook trigger flags"Flag | Description |
---|---|
--topic <topic> |
The requested event topic. You can pass the webhook topic using the GraphQL enum value or the webhook topic name. For example, you can request the orders/create webhook topic by passing ORDERS_CREATE (GraphQL API style) or orders/create (REST API style).For a complete list of topics, refer to the GraphQL Admin API reference, the REST Admin API reference, and the Mandatory webhooks guide. |
--api-version <version> |
API version of the event topic, in the format YYYY-MM or unstable . If the topic isn't available in the specified version, then the webhook payload isn't sent. |
--client-secret <value> |
Your app's client secret. This secret is used to generate and return a X-Shopify-Hmac-SHA256 header, which lets you validate the origin of the response that you receive. |
--delivery-method <option> |
The method chosen to deliver the topic payload. Options: http , google-pub-sub , event-bridge |
--address <address> |
The URL where the webhook payload should be sent. For each delivery method, you need to provide a different address type:
|
Lists the available commands and describes what they do.
You can add a help flag to any command to learn more about it. Use --help
or -h
.
Lists the version of Shopify CLI included in the project.
If nothing is returned from this command, then your project isn't using Shopify CLI 3.0 or higher, and you might need to migrate.
Shopify CLI acts as a dependency of your app. This command upgrades the @shopify/cli
and @shopify/app
dependencies to their latest versions.
upgrade flags
Anchor link to section titled "upgrade flags"Flag | Description |
---|---|
--path <path> |
The path to your app directory. |
Starts a search on Shopify.dev.
Search the Shopify.dev docs by optionally passing a query argument to the command.