npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

shipflow-cli

v0.1.1

Published

CLI for ShipFlow, a self-hosted CI/CD and static-site deployment server

Readme

ShipFlow CLI

ShipFlow CLI is the command-line client for ShipFlow, a self-hosted CI/CD and release automation platform for static websites.

Install the CLI with npm, connect it to a ShipFlow server you control, and deploy a site from a Git repository. ShipFlow can build and test your project in an isolated container, keep versioned release artifacts, deploy to the built-in site server or your own Linux server over SSH, verify the candidate, and activate or roll back releases.

Important: Installing shipflow-cli installs the client only. You also need a running ShipFlow server. The CLI does not provide a hosted service, and it does not automatically provision infrastructure during a normal deployment.

Contents

Requirements

For the CLI

  • Node.js 22 or newer
  • npm
  • A terminal (Linux, macOS, or WSL examples are shown below)
  • Access to a ShipFlow server

For a self-hosted ShipFlow server

  • A Linux host with Docker Engine and Docker Compose v2.24 or newer
  • About 2 vCPU and 4 GB RAM is a comfortable starting point for one build at a time
  • A domain name and TLS reverse proxy for access from outside the server

ShipFlow includes PostgreSQL and Redis in its Compose stack. Artifact storage can use a local Docker volume; an S3-compatible bucket is optional.

1. Install the CLI

Install the published npm package globally:

npm install --global shipflow-cli

Verify the install:

shipflow --version
shipflow --help

To upgrade to the latest published version later:

npm install --global shipflow-cli@latest

2. Set up a ShipFlow server

If you already have a working ShipFlow server, skip to Connect the CLI.

On the Linux machine that will host ShipFlow:

git clone https://github.com/shivsingh78/shipflow.git
cd shipflow
cp .env.example .env

Generate random values for the secrets required by the server. Run the command separately for each value and do not reuse one value for every setting:

openssl rand -hex 32

Edit .env and configure at least:

| Variable | What to set | |---|---| | SHIPFLOW_API_TOKEN | A long, random bearer token used by the CLI to authenticate with the API | | DB_PASSWORD | A strong password for the bundled PostgreSQL database | | SHIPFLOW_ALLOWED_REPO_PREFIXES | URL prefixes for repositories the server is allowed to build, for example https://github.com/your-user/ | | SHIPFLOW_SECRETS_KEY | A separate 64-character hex key if you will use the SSH deployment target |

Keep .env private. Do not commit it, paste it into chat, or include it in a README. Restrict its permissions:

chmod 600 .env

Start the server:

docker compose up -d --build --wait
docker compose ps
curl -fsS http://127.0.0.1:8000/health

The health endpoint should return a successful response when the API is ready.

Make the API safely reachable

By default, the API and built-in site port bind to localhost. For a remote CLI, put a TLS reverse proxy such as Caddy or nginx in front of the API, then use its HTTPS URL when logging in. For example, the API might be available at https://shipflow-api.example.com.

The CLI refuses to send an API token over plain HTTP to a non-local server. Do not expose PostgreSQL or Redis to the public internet.

For server upgrades, TLS, backups, limits, and isolation guidance, see the self-hosting guide.

3. Connect the CLI to your server

From your workstation, run:

shipflow login --server https://shipflow-api.example.com

Replace the example hostname with your ShipFlow API's real HTTPS address. The CLI prompts for the API token with hidden input. Enter the value of SHIPFLOW_API_TOKEN configured on the server; never put the token in a source file or commit it.

Credentials are saved in ~/.config/shipflow/credentials.json with restrictive file permissions and are associated with the server URL.

Check the connection:

shipflow doctor

doctor checks the configuration, API authentication, server health, queue/worker status, artifact storage, secrets, and deployment-target prerequisites where applicable.

4. Configure a project

Open a terminal in your website repository—the directory containing its package.json—and run:

shipflow init

The interactive setup asks for your repository, branch, build settings, and deployment target, then writes shipflow.yml in the current directory. Review the generated file before deploying.

A basic example for a Vite/React static site is:

version: 1

project:
  name: my-site
  repository: https://github.com/your-user/my-site
  branch: main

build:
  install: auto
  command: auto
  output: dist
  test: auto

deployment:
  target: shipflow

verification:
  path: /
  expectStatus: 200

Adjust the project name and repository URL. The repository must match one of the prefixes configured in SHIPFLOW_ALLOWED_REPO_PREFIXES on the server.

Build settings

  • install: auto detects npm, pnpm, or Yarn from the repository lockfile and uses a frozen/lockfile-based install when possible.
  • command: auto runs the build script from package.json when available.
  • output is the generated static-site directory (commonly dist, build, or out). It must contain index.html.
  • test: auto attempts to run the project's test script. If no usable test script exists, the result can be SKIPPED, not PASSED. Add tests to your project to get meaningful test coverage.

The complete configuration reference is in docs/configuration.md.

5. Deploy to the built-in site server

For a site served by ShipFlow itself, make sure the configuration includes:

deployment:
  target: shipflow

Then from the project directory run:

shipflow doctor
shipflow deploy

The CLI reports the release ID, pipeline stages, test status, and public URL when deployment succeeds. Make sure the server's site endpoint is reachable by visitors, and configure its domain/TLS via your reverse proxy as needed.

6. Deploy to your own server with SSH

Choose the SSH target when you want to serve the site using nginx or Caddy on a Linux VPS you control. You need a non-root deployment user and a web server configured to serve the project's current directory.

Prepare the destination server

The following is a starting example for a Debian/Ubuntu server. Adapt the host and directory to your setup:

sudo adduser --disabled-password deploy
sudo mkdir -p /srv/my-site
sudo chown deploy:deploy /srv/my-site

Configure nginx or Caddy to serve /srv/my-site/current. ShipFlow creates versioned directories under releases/ and uses a current symlink to activate a release. The target server needs a POSIX shell, tar, sha256sum, and GNU mv with -T support.

Create a dedicated deployment key

On your workstation, generate a key specifically for this project:

ssh-keygen -t ed25519 -f ~/.ssh/my_site_deploy_key -N ""

Add ~/.ssh/my_site_deploy_key.pub to the deployment user's authorized_keys on the destination server. Do not use your personal login key or a root account for deployment.

Configure the SSH target

Run shipflow init and select the ssh target. It asks for the host, port, deployment user, remote path, public URL, and server host key. Verify the host-key fingerprint on the destination server before trusting it. Do not blindly trust a key returned by a network scan.

The generated config includes settings like these (use the full, verified hostKey value generated/confirmed for your own server):

deployment:
  target: ssh
  ssh:
    host: server.example.com
    port: 22
    user: deploy
    path: /srv/my-site
    hostKey: "ssh-ed25519 REPLACE_WITH_FULL_VERIFIED_PUBLIC_HOST_KEY"
    privateKeySecret: SSH_PRIVATE_KEY
    url: https://www.example.com/

Store the private deployment key on the ShipFlow server as a project secret. From the project directory, run:

shipflow secrets set SSH_PRIVATE_KEY --from-file "$HOME/.ssh/my_site_deploy_key"

This reads the private key from the local file and transmits it to the ShipFlow API; it does not print the key. Use a trusted HTTPS API endpoint. The ShipFlow server encrypts project secrets at rest using SHIPFLOW_SECRETS_KEY.

Then check and deploy:

shipflow doctor
shipflow deploy

See the SSH target and self-hosting notes for further details.

Useful commands

Run commands in the project directory unless noted otherwise.

| Command | Purpose | |---|---| | shipflow --help | List CLI commands and global options | | shipflow --version | Show the installed CLI version | | shipflow login --server <URL> | Connect to a ShipFlow server | | shipflow logout | Remove saved CLI credentials | | shipflow init | Create shipflow.yml interactively | | shipflow doctor | Diagnose config, server, secrets, and target checks | | shipflow deploy | Register/update the project and start a release | | shipflow deploy --ref <branch-or-commit> | Deploy a specific ref supported by the server | | shipflow status <release-id> | Show one release's status | | shipflow logs <release-id> | View pipeline logs and notifications | | shipflow releases --project <name> | List recent releases for a project | | shipflow rollback <release-id> | Reactivate an earlier successful release | | shipflow cancel <release-id> | Cancel a queued or running release before activation | | shipflow secrets set <NAME> --from-file <path> | Store a deployment secret from a file | | shipflow secrets list | List secret names without showing values | | shipflow secrets rm <NAME> | Delete a project secret | | shipflow projects | List registered projects | | shipflow targets | Show supported deployment targets |

Add --json to supported commands for machine-readable output. Exit codes are 0 for success, 1 for an operation failure, 2 for usage/configuration errors, 3 for unreachable/unauthorized server errors, and 4 for a timeout waiting for a release.

Multiple environments

Use a separate config file and project name for each environment, for example:

shipflow doctor -c shipflow.staging.yml
shipflow deploy -c shipflow.staging.yml

Each project has its own release history and secrets.

Optional AWS EC2 wizard

The CLI also includes an experimental AWS EC2 wizard:

shipflow cloud help
shipflow cloud deploy
shipflow cloud status
shipflow cloud destroy

Read the help output carefully before running these commands. AWS credentials and permissions must be configured for your account. Provisioning EC2 and related infrastructure can incur charges. destroy is destructive and may delete resources created by the wizard; inspect the planned actions and preserve anything you need before confirming. This optional wizard is separate from ordinary shipflow deploy deployments.

CI environments

For automation, you can supply the server URL and token via environment variables instead of running the interactive login flow:

export SHIPFLOW_API_URL="https://shipflow-api.example.com"
export SHIPFLOW_API_TOKEN="${SHIPFLOW_API_TOKEN}"
shipflow doctor
shipflow deploy

Configure SHIPFLOW_API_TOKEN as a protected CI secret in your CI provider. Do not hard-code it in a workflow file or print it in logs. The repository must be accessible to the ShipFlow server, and the server's repository allowlist must permit it.

Troubleshooting

Missing or invalid API token / HTTP 401

Confirm the token entered at login is the same as the server's configured SHIPFLOW_API_TOKEN. If that server setting changes, log in again:

shipflow login --server https://shipflow-api.example.com
shipflow doctor

The server is reachable, but no worker is alive

On the ShipFlow host, check services and logs:

docker compose ps
docker compose logs --tail=100 api worker

SSH_PRIVATE_KEY is missing

From the directory containing shipflow.yml, store the private key as a project secret:

shipflow secrets set SSH_PRIVATE_KEY --from-file "$HOME/.ssh/my_site_deploy_key"
shipflow doctor

SSH permission or host-key mismatch

Check that the public key is installed for the configured non-root user, the user can write to the configured directory, and the pinned host key matches the actual server key. If the server was rebuilt, verify its new fingerprint out-of-band before updating hostKey.

Build or test stage fails

Check the release logs:

shipflow logs <release-id>

Run the same build/test scripts locally, verify that the expected output directory contains index.html, and ensure that required dependencies can be installed using the project's lockfile.

For more troubleshooting advice, consult the self-hosting guide.

Security notes

  • Never commit .env, API tokens, private SSH keys, or credential files.
  • Keep the ShipFlow API behind HTTPS when accessed remotely. Do not send tokens to a remote API over plain HTTP.
  • Use a dedicated, non-root deployment user and a dedicated key for each deployment target.
  • Put deployment credentials in project secrets, not shipflow.yml or build-time environment variables.
  • Back up SHIPFLOW_SECRETS_KEY securely. If it is lost, existing encrypted project secrets cannot be decrypted.
  • ShipFlow is intended for a single owner or trusted team. It is not hardened for anonymous multi-tenant workloads; read the server's isolation notes before exposing it to untrusted users.
  • Infrastructure, storage, and network costs are your responsibility.

Uninstall

npm uninstall --global shipflow-cli

To remove saved CLI credentials as well, run shipflow logout before uninstalling, or delete ~/.config/shipflow after confirming you no longer need the saved server credentials.

Links