The Altera CLI tool is a powerful command-line interface for interacting with your Shopify store through the Altera app. It provides an efficient way to manage your Shopify files and run data imports and exports. While we do not provide direct API access to Altera, this tool allows you to manage your store's data and files from the command line and to automate your workflows.

We launched the CLI tool in September 2025. If you have any questions or feedback we would love to hear from you.

Getting Started

Important: Keep your API key private as anyone with access will be able to access your store's data.

Install the Altera app from the Shopify App Store
Navigate to Settings → API Keys
Enter a contact email and save the settings
Then generate an API key and copy it to your clipboard
In your terminal run npx altera shop add to connect your store to the CLI

Command Reference

This section provides a reference for all the commands available in the Altera CLI.

Shop Management

shop add [shopDomain] - Connect a new Shopify store to the CLI
shop list - View all configured shops
shop use [shopDomain] - Switch between different shops
shop remove [shopDomain] - Remove a shop configuration
shop test [shopDomain] - Test API connection for a specific shop

File Management

The files subcommand allows you to upload and download files from the Shopify Files section. Each time you upload or downloads files you will also get an Excel file of the files in the Altera format.

files download [localDir] - Download files from Shopify to local folder
Options:
- --filename <filename> - Filter files by filename
- --media_type <type> - Filter by media type (IMAGE, EXTERNAL_VIDEO, MODEL_3D, VIDEO, FILE)
files upload [filePath] - Upload a file to Shopify

Example Commands

Download all files from Shopify to a local folder:

$ npx altera files download local_folder
Downloading Files
-----------------
URL: https://admin.shopify.com/store/example-store/apps/altera/job/q17bPE/
Output directory: ./local_folder
Excel summary: ./local_folder/Files_2025-09-24_062200.xlsx
[x] Preparing file list (1029)
[x] Creating local directory
[x] Downloading files (1029/1029)
1029 files downloaded to ./local_folder

Download all images from Shopify that contain 'shoes' in the filename:

$ npx altera files download local_folder --filename shoes --media_type IMAGE

Upload files from a local folder to Shopify:

$ npx altera files upload ./product_images/*.jpg
Uploading Files
-----------------
URL: https://admin.shopify.com/store/example-store/apps/altera/job/ED2k8q/
Excel summary: File_Upload_2025-09-24_063407.xlsx
[x] Uploading files (4/4)
[x] Waiting for Shopify to process files
[x] Download summary
File upload job completed successfully

Export Operations

Create and manage export jobs to download Shopify data as spreadsheets.

export create [resources...]

Create a new export job with one or more resources.

Resource Syntax:

Each resource can be specified with optional parts:

<resource>[:<part1>,<part2>...]

For example:

products - Export products with general fields only
products:general,media - Export products with general and media fields
catalogs:general,price_list - Export catalogs with general and price list fields

Available Resources:

products - Product catalog data
catalogs - Catalog and market pricing
customers - Customer information
orders - Order history
articles - Blog posts
companies - B2B company data
discounts - Discount codes and rules
draft_orders - Draft order data
files - Media files
menus - Navigation menus
metaobjects - Custom metaobjects
pages - Store pages
redirects - URL redirects
shop - Store settings
metafield_definitions - Metafield schemas
metaobject_definitions - Metaobject schemas
events - Store activity logs
payouts - Payment information
blogs - Blog settings
manual_collections - Manual collections
smart_collections - Smart collections

Each resource supports different field groups that can be specified using the colon syntax (e.g., products:general,media).

Options:

-s, --shop <alias> - Select which configured shop to use
-f, --filter <expr> - Add a filter expression (repeatable)
--format <xlsx|csv|zip> - File format (default: xlsx)
--filename <pattern> - Custom filename with placeholders
--url-visible - Make the download URL public
-t, --transform <resource>=<uuid> - Apply data transformation
--download-to <dir> - Download file to directory after completion
--datetime-format <format> - Datetime format (see Formatting Options)
--phone-format <format> - Phone number format (see Formatting Options)
--phone-cell-format <format> - Phone cell format for Excel (see Formatting Options)

Filename Placeholders:

#{{shop}} - Shop alias
#{{resource}} - Resource name
#{{date}} - Current date (YYYY-MM-DD)
#{{time}} - Current time (HHMMSS)
#{{timestamp}} - Combined date and time
#{{job_id}} - Export job ID
#{{uuid}} - Random unique ID

Filter Syntax:

Filters follow the pattern: <resource>.<field><operator><value>

Supported operators:

= - equals
!= - not equals
^= - starts with
$= - ends with
~= - contains
> - greater than
< - less than
>= - greater than or equal
<= - less than or equal

Examples:

Export products with general info and media:

npx altera export create products:general,media

Export products filtered by handle and date:

npx altera export create products --filter 'products.handle^=shoe-' --filter 'products.published_at>=2025-01-01'

Export catalogs with custom filename:

npx altera export create catalogs:general,price_list --filename 'catalogs-#{{date}}'

Export multiple resources:

npx altera export create products:general,media customers:general orders:general

Formatting Options

Control how datetime and phone fields are formatted in exports.

Datetime Formats (--datetime-format):

Value	Example Output
`iso_with_tz`	`2025-11-26 09:59:04 -0500` (default)
`iso_with_tz_colon`	`2025-11-26 09:59:04 -05:00`
`iso8601`	`2025-11-26T09:59:04-05:00`
`iso_no_tz`	`2025-11-26 09:59:04`
`iso_date_only`	`2025-11-26`
`us_datetime`	`11/26/2025 09:59:04`
`us_datetime_no_sec`	`11/26/2025 09:59`
`us_date`	`11/26/2025`
`uk_date_dash`	`26-11-2025`
`uk_date_slash`	`26/11/2025`

Phone Number Formats (--phone-format):

Value	Example Output	Description
`default`	`+1 555-123-4567`	Pass through as-is (default)
`e164`	`+15551234567`	Strict international format
`international`	`+1 555 123 4567`	Readable international format
`national`	`(555) 123-4567`	National format

Phone Cell Formats (--phone-cell-format):

Value	Example Output	Description
`apostrophe_prefix`	`'555-123-4567`	Prevents Excel auto-formatting (default)
`formula`	`="555-123-4567"`	Excel formula displays as text
`raw`	`555-123-4567`	No prefix

Examples:

Export orders with ISO 8601 datetime format:

npx altera export create orders --datetime-format iso8601

Export customers with strict international phone format and no cell prefix:

npx altera export create customers --phone-format e164 --phone-cell-format raw

Export with US date format and international phone numbers:

npx altera export create orders:general --datetime-format us_date --phone-format international

Import Operations

Create import jobs to upload data from spreadsheets to your Shopify store.

import create <file>

Create a new import job using a local spreadsheet file.

Arguments:

<file> - Path to a local CSV, XLSX, or ZIP file

Options:

-s, --shop <alias> - Select which configured shop to use
--types <list> - Comma-separated sheet-to-type mapping (e.g., products,null,orders)
--analyze-only - Run file analysis only, don't start import
--ignore-warnings - Proceed automatically even with warnings

Behavior:

File Analysis: The file is first analyzed for errors and warnings
Errors will cause the import to fail
Warnings require confirmation unless --ignore-warnings is used
Import Execution: If validation passes, the import starts automatically

Examples:

Import a products file:

npx altera import create ./products.xlsx

Import with explicit sheet type mapping (skip second sheet):

npx altera import create ./multi-sheet.xlsx --types products,null,orders

Analyze file without importing:

npx altera import create ./data.xlsx --analyze-only

Import and auto-proceed on warnings:

npx altera import create ./products.csv --ignore-warnings

Job Management

job status <jobId>

Get the current status of any job (import, export, or file operation).

Arguments:

<jobId> - The unique identifier for the job

Example:

npx altera job status abc123

Plan Requirements

Note: The CLI tool, including import and export commands, is available on the Developer and Pro plans only. The Community plan does not include CLI access.

To use the CLI: