docs
OverviewCommerce APIStorefront APIUser GuideExplorer
Lana Commerce CLI > Usage Guide
Search docs
/
Sign In
OverviewLana Commerce CLIUsage Guide
Usage Guide

A short guide on how to use the Lana Commerce CLI tool.

Built-in Help

As with most CLI tools, the Lana Commerce CLI tool comes with built-in help. Use the --help argument to display the help for the current command. E.g.

lana --help
lana config --help
lana config list --help

Authorization

For most API endpoints of the Lana Commerce API, you need to be authorized. There are two options for Lana Commerce CLI tool:

Authorize Using Login/Password

Use lana login command. This command will interactively prompt you for your email and password. Upon successful authentication, a JSON Web Token (JWT) is obtained and automatically saved to the CLI's configuration file. This JWT is then used for authenticating subsequent API calls.

Authorize Using API Key

Navigate to the Lana frontend app and create an API key. Make sure you added the right permissions or roles to the API key. It's perfectly fine to use Administrator role, which gives full access to the API.

Set it via lana config set jwt <YOUR_KEY>. The default shop_id will be set automatically.

Configuration

You can manage the CLI configuration using the lana config subcommand.

Common config commands:

  • lana config location: Shows the location of the configuration file.
  • lana config list [search]: Lists all or some of the configuration values. You can search for specific entries. Output can be formatted as a table (default) or JSON/CSV.
  • lana config get <name>: Retrieves a specific configuration value.
  • lana config set <name> <value>: Sets a specific configuration value.
  • lana config unset <name>: Resets a specific configuration value to its default.
  • lana config login: Initiates the interactive login process (as described in the Authorization section, this is the same as lana login).

Key Configuration Entries:

  • jwt: The JSON Web Token for API authentication. Managed by lana login.
  • shop_id: The ID of the shop you are interacting with. This is often set automatically after login if you have access to a single shop or a default shop is configured for your user.
  • api: The API domain. Defaults to lana.dev and usually does not need to be changed.
  • device_id: A unique identifier for the device making API calls, automatically generated.

Keeping It Up to Date

Use lana update to automatically update the CLI tool. This command checks for the latest version of the Lana Commerce CLI on GitHub and updates your local binary if a newer version is available. It works by downloading the appropriate archive for your operating system (Linux, Windows, or macOS), extracting the new binary, and replacing the existing one.

Resource Management Commands

The Lana Commerce CLI provides a consistent interface for managing various commerce resources. These commands are typically structured as:

lana <resource-name> <action> [options]

<resource-name> refers to the type of resource you want to manage, such as products, categories, orders, customers, etc. A comprehensive list of available resources can be found by running lana --help.

Common <action> values include:

  • list: Retrieves a list of resources.
  • get <id...>: Retrieves one or more specific resources by their IDs.
  • create: Creates new resources. Often accepts data via command-line options or a JSON file (--data <file-path> or --data - for stdin).
  • modify <id...>: Modifies existing resources. Accepts data similarly to create.
  • delete <id...>: Deletes one or more resources by their IDs.
  • search: Performs a search for resources based on specified criteria.
  • suggest <query>: Provides suggestions for resources based on a query string.
  • export [output-file]: Exports resource data to a CSV file. Options allow specifying columns, IDs, and formatting.
  • import <input-file>: Imports resource data from a CSV file. Requires column mapping.

File Management

The Lana Commerce CLI includes commands for uploading and downloading files. These are typically found under the files resource.

  • lana files upload <...files> Uploads one or more files to Lana Commerce.

    • --shop-id <string>: Specifies the shop ID.
    • --name <string>: Overrides the automatically discovered file name.
    • --content-type <string>: Overrides the automatically discovered Content-Type.
    • --public: Makes the file accessible via a public CDN.

  • lana files download <file-id> [output] Downloads a file by its ID and saves it. If output is not specified or is -, the file content is written to standard output.

    • --shop-id <string>: Specifies the shop ID.

Output Formatting (--format)

Many Lana Commerce CLI commands support the --format option to control how the output data is displayed. This option is crucial for scripting and integrating the CLI with other tools.

The general syntax is:

lana <resource> <action> --format <type:spec>

or for simple formats:

lana <resource> <action> --format <type>

Available Format Types

  • json: Outputs the data as a pretty-printed JSON string. This is useful for programmatic consumption.

    lana products list --format json

  • table: This is the default format for many commands. It presents data in a human-readable table. The table format can be customized using a spec string.

    # Uses default table spec for the 'products list' command
lana products list

# Uses a custom table spec
lana products list --format "table:{id:v=>v.id,title:v=>v.title.toUpperCase(),_title:'30%'}"

    The table format cannot be used with the --stream option for paginated output.

  • csv: Outputs the data in Comma-Separated Values (CSV) format. This is useful for exporting data to spreadsheets or other data analysis tools. The CSV format can also be customized.

    lana products list --format csv
lana products list --format "csv:{ID:v=>v.id,'Product Title':v=>v.title}"

Customizing table and csv Formats

You can customize table and csv output by providing a "spec" string after the format type, separated by a colon (e.g., table:{...} or csv:{...}). This spec is a JavaScript object that defines the columns and how data for each column should be extracted and transformed.

  • Column Definition: Each key-value pair in the spec represents a column.

    • The key is the column header.
    • The value is a function string v => expression where v represents the individual data item (e.g., a product object), and expression is a JavaScript expression to extract or transform the data. Example: {id: v => v.id, name: v => v.name.toUpperCase()}

  • Available Helper Functions in Spec Strings: Within the expression, you can use several built-in helper functions:

    • colors: Access to styling functions from @cliffy/ansi/colors (e.g., colors.bold(v.name)).
    • noop: An identity function v => v.
    • formatCurrency: Formats a numeric value as currency. This function considers the shop's currency settings or a provided currency code.
    • formatSize: Formats a numeric value (bytes) into a human-readable size string (e.g., "10 KiB").

  • Table-Specific Options (keys prefixed with _): These options are only applicable when the format type is table.

    • _hspacing: <number>: Sets horizontal spacing (padding) between table columns. Defaults to 2.
    • _vspacing: <number>: Sets vertical spacing (empty lines) between table rows. Defaults to 0.
    • _header: <boolean>: Determines if the table header is displayed. Defaults to true.
    • _columnName: <number | string>: Defines properties for a specific column named columnName.
      • Width: _id: 10 sets the max width of the "id" column to 10 characters.
      • Percentage Width: _description: "70%" attempts to set the "description" column to 70% of available terminal width, after accounting for other columns.

  • CSV-Specific Options:

    • _header: <boolean>: Determines if the CSV includes a header row. Defaults to true.

Default Specs

Many commands have predefined default specs for table and csv formats. If you use --format table or --format csv without a custom spec, these defaults are used. You can find these default specs within the source code.

Example of a Complex Custom Table Format

lana products list --format "table:{ID: v => colors.yellow(v.id), Title: v => colors.bold(v.title), Handle: v => v.handle, '_ID': 15, '_Title': '40%', '_Handle': '60%', _hspacing: 3, _header: true}"

This command would:

  • Display columns: "ID", "Title", "Handle".
  • Color the ID yellow and the Title bold.
  • Set the "ID" column to a max width of 15.
  • Attempt to size "Title" to 40% and "Handle" to 60% of the remaining width.
  • Use a horizontal spacing of 3.
  • Display the header.

Common Options

Many commands share common options:

  • --shop-id <string>: Specifies the shop to operate on. Can often be omitted if shop_id is set in the global config.
  • --format <format>: Specifies the output format (e.g., table, json, csv). The default is usually table.
  • --data <file-path | ->: Used with create and modify actions to provide input data from a JSON file or stdin.

For detailed options available for each command and subcommand, use the --help flag:

lana <subcommand> --help
lana <resource-name> <action> --help

Usage Examples

Publish Multiple Products

Publish multiple products at once:

lana products modify --published true pd_4VpOA7Z0 pd_LVow1z3G pd_RVo2noAG

List Customers

List all the customer ids and their emails

lana customers list --stream --sort-by created_at --format 'csv:{id:v=>v.id,email:v=>v.email}'

Note that a --stream option is used. It will utilize pagination API to really list all the customers page by page. This option only works when sorting order is specified and a non-table format is used (csv or json). This example also shows you how to specify a custom format.

Export Customers

To export customers (id, email and name columns) into csv file:

lana customers export --columns id,email,name my_file.csv

PREVIOUS
Installation
NEXT
Lana UI