ShipEngine Connect CLI

The ShipEngine Connect CLI is a powerful tool that makes it easier for you to create, run, test, and publish your application.

Prerequisites

Node v12+
You'll need NodeJS version 12.0.0 or greater. You can verify your installed Node version using node --version.

NPM v6+
Node comes with npm. Verify that you have version 6.0.0 or greater by running npm --version.

Git
You'll need to install git in order to use the CLI.

Mac Users
Mac users will need to install the developer tools. If you do not have them installed, you will get the dialog box below when you run the CLI. You can click the Install button in the dialog box.

Installation

To install ShipEngine Connect CLI, run the following command from your terminal:

npm install --global @shipengine/connect

Verify that the CLI was installed correctly:

connect --version

Initialize a New App

Use the connect init command to start building a new application. Rather than starting from scratch, this command will prompt you for information about your app and coding preferences and will then generate all the inital scaffolding for you. For more details, see Creating Your First App.

connect init [OPTIONS] [PATH]

Options

--yes

This option will bypass all the prompts and just use the default values. This is an easy way to quickly create a new app.

--force

This option will overwrite existing files in the output directory without prompting. Use caution with this option.

Arguments

path

By default, the connect init command will create a new app in the current directory, but you can optionally specify a different path. For example, connect init my-new-app will create the app in a new sub-directory named "my-new-app".

Run Your App Locally

The connect start command starts a local server that allows you to invoke your app's methods using http requests.

connect start

Options

--port <number>

The local server runs on port 3006 by default, but you can use this option to change the port number.

Test Your App

The connect test will validate that your connect app is properly structured.

We recommend that you write your own acceptance tests in your project using jest and create requests based off of the requests you get from the test environment. These can be attained by running a connect logs after publishing your app and making request to it in the shipstation test environment.

Manage Environment Variables

The connect env command allows you to set environment variables that will be available to your app once it is published to ShipEngine Connect. This allows you to manage application secrets and configuration data separately from your code and make changes to this data without changing your application code.

You should run this command before publishing your app. The values that are set at the time you run the publish command will be injected into your app once it is hosted in ShipEngine Connect. If you change those variables, you will need to re-publish your app before those changes will take affect in ShipEngine Connect.

When you run the connect env command, you will include one of its subcommands listed below to indicate which environment variable action you would like to perform.

Set Environment Variables

This subcommand sets one or more environment variables.

connect env:set NAME=value NAME_2=value2 ... NAME_N=valueN [OPTIONS]

Copy

Get Environment Variables

This subcommand lists the current value for one or more environment variables.

connect env:get NAME NAME_2 ... NAME_N [OPTIONS]

Copy

List Environment Variables

This subcommand lists the values of all environment variables.

connect env:list [OPTIONS]

Copy

Unset Environment Variables

This subcommand unsets one or more environment variables.

connect env:unset NAME NAME_2 ... NAME_N [OPTIONS]

Copy

Options

--debug

This option enables verbose logging, which can be useful for debugging issues managing variables.

--format

This option formats the output of the connect list command. Set this option to table to list the environment variables in a table format or dotenv to list the environment variables in the dotenv format.

Package Your App

The connect pack command allows you to package your application without publishing it. It moves your dependencies into bundledDependencies, runs npm pack, and creates a tarball in the root of your project that you can inspect.

This provides you with visibility as to exactly what is being sent to ShipEngine Connect. This is useful for ensuring that you are not sending us any sensitive data. It is also helpful in making sure you aren't including any unnecessary files in your package. For example, this may help you identify packages that are listed in your dependencies that should actually be listed in your devDependencies.

We suggest that you use the files property of your package.json file to list which files to allow in the package. Likewise, you can create a .npmignore file to specify which files to exclude from your package.

connect pack

Options

There are no options for this command.

Publish Your App

When you're ready to see your app live on ShipEngine Connect, run the connect publish command. This will publish your app to our development environment for further testing and approval. For more details see Publishing Your Application. This command fist calls the connect pack command to package your app, creates a new deployment to Shipengine Connect, deletes the tarball created by connect pack, and polls ShipEngine Connect for status changes.

connect publish [OPTIONS]

Options

--skip-tests

We normally run your app through our end-to-end test suite to confirm that it functions correctly before publishing it. You can skip the tests using this option.

--no-watch

Use this option if you do not wish to watch the publish or show a progress indicator. You can run the connect info command to check the status of your app deployment.

List Your Apps

This command lists all of your apps

connect apps

Options

There are no options for this command.

View App Info

This command shows information about your app, such as its ID, deployed version, deployment status, etc.

connect info

Options

There are no options for this command.

Print App Logs

This command prints retrieves your app's logs from the server and prints them to the console

connect logs

Options

--all

Shows additional debugging about internal ShipEngine platform calls. By default you will only be shown logs specific to your app.

--format

Choose the format (default or raw) that logs are displayed in. The default is default.

--lines

Show the tail of the ShipEngine platform logs up to 1500 lines. The default is 500.