square-online-cli

Usage

$ npm install -g square-online-cli
$ square-online-cli COMMAND
running command...
$ square-online-cli (--version)
square-online-cli/1.0.0-alpha.7 linux-x64 node-v18.17.0
$ square-online-cli --help [COMMAND]
USAGE
  $ square-online-cli COMMAND
...

Commands

• square-online-cli auth ACCESSTOKEN
• square-online-cli help [COMMANDS]
• square-online-cli theme install
• square-online-cli theme preview
• square-online-cli theme pull
• square-online-cli theme push
• square-online-cli theme watch

square-online-cli auth ACCESSTOKEN

Authorizes Square Online CLI with Access Token.

USAGE
  $ square-online-cli auth ACCESSTOKEN [--verbose] [-f] [--skipPermissionsCheck]

ARGUMENTS
  ACCESSTOKEN  Square Connect Access Token

FLAGS
  -f, --force             Overwrite existing Access Token
  --skipPermissionsCheck  Skip the permissions check for Access Token. By default this will check to see that the token
                          has all the required permissions

GLOBAL FLAGS
  --verbose  Print all API logs in console.

DESCRIPTION
  Authorizes Square Online CLI with Access Token.
  Visit https://developer.squareup.com/ for more information.

EXAMPLES
  $ square-online-cli auth SQUARE_CONNECT_ACCESS_TOKEN

See code: dist/commands/auth.ts

square-online-cli help [COMMANDS]

Display help for square-online-cli.

USAGE
  $ square-online-cli help [COMMANDS] [-n]

ARGUMENTS
  COMMANDS  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for square-online-cli.

See code: @oclif/plugin-help

square-online-cli theme install

Installs theme on a Square Online site.

USAGE
  $ square-online-cli theme install [--verbose]

GLOBAL FLAGS
  --verbose  Print all API logs in console.

DESCRIPTION
  Installs theme on a Square Online site.

EXAMPLES
  $ square-online-cli theme install

square-online-cli theme preview

Prints development preview links for Square Online custom theme sites.

USAGE
  $ square-online-cli theme preview [--verbose] [--siteId <value>]

FLAGS
  --siteId=<value>  ID of Square Online site to you would like to preview, use to skip site selector step.

GLOBAL FLAGS
  --verbose  Print all API logs in console.

DESCRIPTION
  Prints development preview links for Square Online custom theme sites.

EXAMPLES
  $ square-online-cli theme preview

square-online-cli theme pull

Clone Square Online Theme Files Locally

USAGE
  $ square-online-cli theme pull [--verbose] [--siteId <value>] [--accessToken <value>] [--yes] [--themeDir
    <value>]

FLAGS
  --accessToken=<value>  Use this flag to pass in an access token. If not passed the CLI will look for an access token
                         saved during "auth" command.
  --siteId=<value>       The Square Online site id that you would like to pull files from.
  --themeDir=<value>     Path to theme directory. If the directory does not exist it will be created.
  --yes                  Use this flag to skip the confirmation prompts

GLOBAL FLAGS
  --verbose  Print all API logs in console.

DESCRIPTION
  Clone Square Online Theme Files Locally

EXAMPLES
  $ square-online-cli theme pull

square-online-cli theme push

Push your local theme files to your Square Online site. Files with the following patterns will be ignored by default: /_darcs/,/CVS/,/config.yml/,/node_modules/,/.git/,/.DS_Store/,/.soignore/,/.dockerignore/,/.gitmodules/, as well as any patterns within the /theme/.soignore file

USAGE
  $ square-online-cli theme push [--verbose] [--themeDir <value>] [--siteId <value>] [--omitDelete]
    [--accessToken <value>] [--yes]

FLAGS
  --accessToken=<value>  Use this flag to pass in an access token. If not passed the CLI will look for an access token
                         saved during "auth" command.
  --omitDelete           If set the CLI will skip any delete operations during syncing
  --siteId=<value>       The Square Online site id that you would like to push files to.
  --themeDir=<value>     Path to theme directory.
  --yes                  Use this flag to skip the confirmation prompts

GLOBAL FLAGS
  --verbose  Print all API logs in console.

DESCRIPTION
  Push your local theme files to your Square Online site. Files with the following patterns will be ignored by default:
  /_darcs/,/CVS/,/config.yml/,/node_modules/,/.git/,/.DS_Store/,/.soignore/,/.dockerignore/,/.gitmodules/, as well as
  any patterns within the /theme/.soignore file

EXAMPLES
  $ square-online-cli theme push

square-online-cli theme watch

Watch your theme directory and automatically upload file changes to Square Online. Files with the following patterns will be ignored by default: /_darcs/,/CVS/,/config.yml/,/node_modules/,/.git/,/.DS_Store/,/.soignore/,/.dockerignore/,/.gitmodules/ as well as any patterns within the /theme/.soignore file

USAGE
  $ square-online-cli theme watch [--verbose] [--themeDir <value>] [--siteId <value>] [--hotReload] [--omitDelete]

FLAGS
  --hotReload         Set this flag to print the preview links and enable hot reloading
  --omitDelete        If set the CLI will skip any delete operations during syncing
  --siteId=<value>    The id of the Square Online site you would like to sync to.
  --themeDir=<value>  Path to theme directory for watching.

GLOBAL FLAGS
  --verbose  Print all API logs in console.

DESCRIPTION
  Watch your theme directory and automatically upload file changes to Square Online. Files with the following patterns
  will be ignored by default:
  /_darcs/,/CVS/,/config.yml/,/node_modules/,/.git/,/.DS_Store/,/.soignore/,/.dockerignore/,/.gitmodules/ as well as any
  patterns within the /theme/.soignore file

EXAMPLES
  $ square-online-cli theme watch

CI/CD Usage

The theme pull and theme push commands support automated workflows. Passing in an accessToken flag will skip using any on saved through the auth command. themeDir flags can be either relative or absolute. yes will skip any steps that usually require a user confirmation to continue.

square-online-cli theme pull --siteId=site_693636287506607541 --themeDir=./brisk-theme --accessToken=YOUR_ACCESS_TOKEN --yes
square-online-cli theme push --siteId=site_693636287506607541 --themeDir=./brisk-theme --accessToken=YOUR_ACCESS_TOKEN --yes

Getting Started

• Install Node.
• Install NVM.
• nvm use
• npm ci

Developing Locally

[!WARNING] You can't use the CLI locally unless you have Ecom-Connect running locally as well!

Development ENV Variables:

PREVIEW_HOST=https://staging.weebly.net // for staging or use your local weld host https://${ldap}.development.weebly.net
API_HOST=https://connect.squareupstaging.com // for staging or http://127.0.0.1:12358 for local ecom-connect depending on where it is serving. 

When testing against weld hybrid / staging sites use the accesstoken from developer.squareupstaging.com in the auth command. Can be personal access token or OAuth token.

./bin/dev.js auth {accessToken}

[!NOTE] Running dev.js requires ts-node. Install globally via npm install -g ts-node

When testing with ecom-connect running locally, modify the access token as follows, substituting the ${merchantToken} with the merchant token of the site you are targeting. More info on ecom-connect here https://github.com/squareup/go-square/tree/master/ecom-connect

./bin/dev.js auth ::${merchantToken}: --skipPermissionsCheck

Use the ./bin/dev.js to run the commands while developing the CLI.

./bin/dev.js COMMAND ARGS --flag

Contribution Guide

The CLI is based on the OCLIF . UI components leverage Ink .

Adding a new command.

Create a new command by creating a new command file inside the src/commands/ directory. Commands can be grouped together in topics which are sub directories within the src/commands/ directory. For example, to add a new command square-online-cli theme duplicate we would create a file src/commands/theme/duplicate.ts.

After you create your new command. Please add a test for it and update the readme command documentation.

npm run generate-readme

Adding a new component

If you need to create a new custom UI component. Please use the Ink library and put your component and put it src/components/ui/ directory and a wrapper to call it from the src/components/. This is just in case we need to pivot to a different component framework.

Testing

We are using Vitest as our framework because it has ESM support. When you add a command please add a test for it within the /test/commands directory. See existing tests as an example. Please mock any filesystem, api or stdin calls that may be run during the command.