SPAship CLI

A command line interface for SPAship.

• SPAship CLI
• Usage
• Commands
• SPAship environments & .spashiprc
• Writing tests

Usage

$ npm install -g @spaship/cli
$ spaship COMMAND
running command...
$ spaship (-v|--version|version)
@spaship/cli/1.5.6 darwin-x64 node-v18.12.1
$ spaship --help [COMMAND]
USAGE
  $ spaship COMMAND
...

Commands

• spaship deploy [ARCHIVE]
• spaship env
• spaship help [COMMAND]
• spaship init

spaship deploy [ARCHIVE]

deploy to a SPAship host

USAGE
  $ spaship deploy [ARCHIVE]

ARGUMENTS
  ARCHIVE  An archive (zip, tarball, or bzip2) file containing SPA static assets and a spaship.yaml file. You can omit
           this if you specify the build artifact path as `buildDir` in the spaship.yaml file.

OPTIONS
  -P, --preview            deploying into temporary preview environment.
  -b, --builddir=builddir  path of your SPAs artifact. Defaults to 'buildDir' if specified in the spaship.yaml.

  -e, --env=env            [default: default] either the name of a SPAship environment as defined in your .spashiprc.yml
                           file, or a URL to a SPAship environment

  -p, --path=path          a custom URL path for your app under the SPAship domain. Defaults to the 'path' in your
                           spaship.yaml. ex: /my/app.

  -r, --ref=ref            [default: undefined] a version tag, commit hash, or branch to identify this release

  --apikey=apikey          a SPAship API key

  --image=image            image (url) for the containerized deployment [SSR].

  --prid=prid              prid is to enable temporary preview environment in a optimized way. ex: pass the pull request
                           id.

DESCRIPTION
  Send an archive containing a SPA to a SPAship host for deployment.  Supports .tar.gz/.tgz, .zip, and .tar.bz2.

EXAMPLES
  $ npm pack && spaship deploy your-app-1.0.0.tgz # deploying an archive created with npm pack
  $ spaship deploy # deploying a buildDir directory

See code: src/commands/deploy.js

spaship env

set env for .spashiprc.yml file (for setting environment & authentication).

USAGE
  $ spaship env

OPTIONS
  -n, --name=name  [default: undefined] name of the environment
  -u, --url=url    [default: undefined] url of the environment
  --apikey=apikey  a SPAship API key

See code: src/commands/env.js

spaship help [COMMAND]

display help for spaship

USAGE
  $ spaship help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
  --all  see all commands in CLI

See code: @oclif/plugin-help

spaship init

initialize a SPAship config file for your app.

USAGE
  $ spaship init

OPTIONS
  -b, --builddir=builddir  path of your SPAs artifact. Defaults to 'buildDir' if specified in the spaship.yaml.
  -d, --dist=dist          the URL path for dist folder
  -m, --file=file          the URL path for spaship.yaml file
  -n, --name=name          a human-friendly title for your app
  -p, --path=path          the URL path for your app under the SPAship domain. ex: /my/app
  -s, --[no-]single        route all non-asset requests to index.html
  --overwrite              overwrite existing spaship.yaml

DESCRIPTION
  Without arguments, init will ask you a few questions and generate a spaship.yaml config file.  The answers can also be
   passed in as CLI options.

See code: src/commands/init.js

SPAship environments & .spashiprc

(As a rule of thumb, spaship.yaml files are consumed by the SPAship API, whereas spashiprc files are consumed by the CLI)

spashiprc files provide an alternative to typing out --apikey KEY and --env URL every time you run spaship commands. You can use a spashiprc file to define an environment name (like qa) along with its URL and API key, after which you can run spaship deploy --env qa. The URL and API key will be read from your spashiprc file.

Do not commit API keys to your project's version control. If you do, I'll know. See spashiprc layering for how to avoid committing API keys.

spashiprc files are optional, but very convenient if you plan to do deployments from your dev environment. If your deployments are done by a CI/CD server, you probably don't need a spashiprc file and will be better off using --env URL and --apikey KEY.

spashiprc layering

To separate environment URLs from API keys, you can "layer" two spashiprc files together. After the spaship command finds a spashiprc file, it continues searching parent directories for other spashiprc files. If any secondary spashiprc files are found, their values are merged together. If there are conflicting values, the values from the child directory (nearer to your project) will win.

This allows you to put a spashiprc file containing your SPAship URLs in your project's source control, and a secondary spashiprc file containing API keys in a parent directory, not in your project's source control.

For an example, see spashiprc-layering-example.

spashiprc examples

spashiprc with default environment

This spashiprc file defines a default environment which will be used whenever --env is not provided.

.spashiprc.yml

envs:
  default:
    url: https://localhost:8008
    apikey: 57d5c061-9a02-40fc-a3e4-1eb3c9ae6a12

Now when you run spaship commands, the --env flag is optional. When it's omitted, the default environment will be used.

spaship deploy MyProject-1.0.0.tgz

spashiprc layering example

$HOME/.spashiprc.yml

envs:
  qa:
    apikey: 57d5c061-9a02-40fc-a3e4-1eb3c9ae6a12
  prod:
    apikey: 70f19422-bf53-44b1-b664-f9b4636bea61

$HOME/projects/MyProject/.spashiprc.yml

envs:
  qa:
    url: https://qa.spaship.io
  prod:
    url: https://spaship.io

When you run spaship commands from within $HOME/projects/MyProject, both of the above spashiprc files will be loaded and merged together, forming a complete definition of URL+API key for each environment.

Such as:

cd $HOME/projects/MyProject
spaship deploy --env prod MyProject-1.0.0.tgz

cd $HOME/projects/MyProject
spaship deploy --env=<your deploy url or alias name (if configured in spashiprc)> --builddir=<optional as it can be configured in spaship.yaml> --apikey=<your api key (optional if configured in spashiprc)>

Writing tests

Tests are written using oclif's testing tools. See oclif's testing documentation for more.