@spaship/cli

A command line interface for SPAship!

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
@spaship/cli
39971.5.614 days ago3 years agoMinified + gzip package size for @spaship/cli in KB

Readme

SPAship CLI
A command line interface for SPAship.
oclif Version Downloads/week License
Usage
```sh-session $ 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 ...
<!-- usagestop -->

# Commands

<!-- commands -->
* [`spaship deploy [ARCHIVE]`](#spaship-deploy-archive)
* [`spaship env`](#spaship-env)
* [`spaship help [COMMAND]`](#spaship-help-command)
* [`spaship init`](#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](https://github.com/spaship/spaship/blob/v1.5.6/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](https://github.com/spaship/spaship/blob/v1.5.6/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](https://github.com/oclif/plugin-help/blob/v3.3.1/src/commands/help.ts)_

## `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](https://github.com/spaship/spaship/blob/v1.5.6/src/commands/init.js)_
<!-- commandsstop -->

# 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](#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-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**

```yaml
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.