FlexSite CLI

Command-line tool for managing FlexSite projects. Download and import database and files backups to your local Lando or DDEV environment.

Installation

npm install -g @flexsiteio/cli

Quick Start

1. Get an access token from your FlexSite dashboard under Profile > Access Tokens

2. Login with your token:

   flexsite auth login

3. Sync your local environment:

   flexsite sync

Commands

Authentication

# Login with a personal access token
flexsite auth login

# Login with token directly (non-interactive)
flexsite auth login --token fst_xxx_...

# Check authentication status
flexsite auth status

# Logout
flexsite auth logout

Database Operations

# Download and import latest database backup
flexsite db pull

# Download to specific environment
flexsite db pull --env <environmentId>

# List available backups
flexsite db list

# Download without importing
flexsite db pull --no-import

Files Operations

# Download and extract latest files backup
flexsite files pull

# Download to specific environment
flexsite files pull --env <environmentId>

# List available backups
flexsite files list

# Download without extracting
flexsite files pull --no-import

Sync (Database + Files)

# Sync both database and files
flexsite sync

# Sync only database
flexsite sync --db-only

# Sync only files
flexsite sync --files-only

Configuration

# Show current configuration
flexsite config show

# Set default organization
flexsite config set org <orgId>

# Set default project
flexsite config set project <projectId>

# Set default environment
flexsite config set env <envId>

# Show config file path
flexsite config path

Composer Migration

Transform composer.json from other platforms (Pantheon, Acquia, Platform.sh) to FlexSite format.

# Check composer.json for FlexSite compatibility
flexsite composer check

# Fix composer.json for FlexSite (interactive)
flexsite composer fix

# Fix with project name specified
flexsite composer fix --name my-project

# Preview changes without modifying files
flexsite composer fix --dry-run

# Create backup before modifying
flexsite composer fix --backup

# Skip adding performance packages
flexsite composer fix --skip-performance

# Specify custom file path
flexsite composer fix -f path/to/composer.json

What composer fix does:

| Change | Description | |--------|-------------| | Name | Updates to flexsite/{project-name} | | Repositories | Adds FlexSite package repository, removes platform-specific paths | | Packages | Removes Pantheon/Acquia packages, adds flexsite/fs_performance, drupal/redis, drupal/purge, drupal/varnish_purge | | Installer paths | Adds recipes/{$name} for Drupal recipes, removes Quicksilver | | Scaffold | Removes platform-specific file mappings | | Scripts | Removes platform-specific composer scripts |

Supported platforms:

• Pantheon (pantheon-upstreams/drupal-composer-managed)
• Acquia (acquia/blt)
• Platform.sh (platformsh/config-reader)

Remote Drush, WP-CLI & SSH

Run Drush/WP-CLI commands and open a read-only inspection shell in your FlexSite environments over a hardened SSH gateway. The CLI shells out to your local ssh client — the same model as Terminus/Acquia. Environments are immutable: code and credentials are never editable or readable over SSH.

How authentication works

There are two independent credentials:

| Purpose | Credential | Set up with | |---------|-----------|-------------| | Control plane (list projects/envs, manage keys) | Personal access token (PAT) | flexsite auth login | | SSH transport (the actual drush/shell session) | An SSH key pair | flexsite ssh-key upload |

The CLI manages its own dedicated key pair at ~/.flexsite/id_ed25519 (separate from your personal ~/.ssh keys). flexsite ssh/drush/wp use that key explicitly (ssh -i ~/.flexsite/id_ed25519 -o IdentitiesOnly=yes), so it works the same on your host and inside Lando/DDEV containers — no SSH agent, host-key mounting, or agent forwarding required.

Setup (one time)

# 1. Authenticate the control plane (needs a PAT with the ssh:access and/or
#    drush:execute scope — create it in the dashboard under Profile > Access Tokens)
flexsite auth login

# 2. Generate + upload the FlexSite SSH key. With no path, this generates
#    ~/.flexsite/id_ed25519 (if missing) and uploads the public half.
flexsite ssh-key upload --tier both        # drush + read-only shell
# or limit the tier:
flexsite ssh-key upload --tier drush       # remote drush/wp only
flexsite ssh-key upload --tier shell       # read-only inspection shell only

# Manage keys
flexsite ssh-key list
flexsite ssh-key remove [id]

Usage

# Remote Drush (requires the drush:execute tier). Use `--` before the command.
flexsite drush <project>.<env> -- cr
flexsite drush <project>.<env> -- status

# Remote WP-CLI (WordPress sites)
flexsite wp <project>.<env> -- cache flush

# Omit the reference to pick a project/environment interactively
flexsite drush -- cr
flexsite ssh

# Read-only inspection shell (requires the ssh:access tier)
flexsite ssh <project>.<env>

Using it inside Lando or DDEV

Because the key lives in ~/.flexsite, the simplest approach is to run flexsite ssh-key upload once in the same environment where you run flexsite ssh/drush:

Lando — the CLI runs inside the app container, so ~/.flexsite is the container's home. Run setup inside the container:

lando ssh -c "flexsite auth login"
lando ssh -c "flexsite ssh-key upload --tier both"
lando flexsite drush <project>.<env> -- cr

Interactive shell (flexsite ssh) needs a TTY. A plain lando flexsite ssh does not always allocate a terminal, which leaves the shell hanging with no prompt. Open an interactive container shell first, then run flexsite there:

lando ssh                 # drops you into the app container with a real TTY
flexsite ssh <project>.<env>

flexsite drush/flexsite wp don't need a TTY and work fine via lando flexsite drush … directly.

To persist the key and token across lando rebuild, mount ~/.flexsite from the host into the container in your .lando.yml:

services:
  appserver:
    overrides:
      volumes:
        - "$HOME/.flexsite:/var/www/.flexsite"

Then run flexsite ssh-key upload once (on host or in the container) and it is shared by both.

DDEV — add the config dir as a mount so it persists and is shared with the host, in .ddev/docker-compose.flexsite.yaml:

services:
  web:
    volumes:
      - "${HOME}/.flexsite:/home/.flexsite"
    environment:
      - HOME=/home

Then:

ddev exec flexsite auth login
ddev exec flexsite ssh-key upload --tier both
ddev exec flexsite drush <project>.<env> -- cr

For the interactive shell, run it from a TTY: ddev ssh first, then flexsite ssh <project>.<env> (a non-interactive ddev exec flexsite ssh has no terminal and will be refused with guidance).

Alternatively, if you already have a key you want to reuse, upload it with flexsite ssh-key upload /path/to/key.pub and point the CLI at the private half with export FLEXSITE_SSH_IDENTITY=/path/to/key.

Notes & limits

• Interactive shell is read-only. Code/vendor/config are immutable; only sites/default/files is writable. settings.php/wp-config.php are locked so credentials are never readable. Run Drush that changes state via flexsite drush (it bootstraps as the web user) rather than inside the shell.
• The first connection prints a host-key trust notice. To pin the gateway host key explicitly, set FLEXSITE_SSH_HOST_KEY to the gateway's public key.
• The read-only shell requires the environment image to include the flexssh user (recent images). If the shell errors, redeploy the environment; remote flexsite drush works regardless.

Local Environment Support

The CLI automatically detects Lando and DDEV environments and uses the appropriate commands for importing databases and files.

Lando

When a .lando.yml file is present or the LANDO environment variable is set to ON, the CLI will use:

• lando db-import for database imports
• Standard tar extraction for files, with permission fixes via lando ssh

DDEV

When a .ddev/config.yaml file is present or the IS_DDEV_PROJECT environment variable is set to true, the CLI will use:

• ddev import-db for database imports
• Standard tar extraction for files, with permission fixes via ddev exec

Configuration File

The CLI stores configuration in ~/.flexsite/config.json:

{
  "version": 1,
  "tokens": {
    "d112c061": {
      "token": "fst_d112c061_...",
      "userId": "110bc5d0-...",
      "organizationId": "d112c061-...",
      "organizationName": "My Company"
    }
  },
  "defaults": {
    "organizationId": "d112c061-...",
    "projectId": "727aa8c7-...",
    "environmentId": "f9b72cdd-..."
  }
}

Environment Variables

• FLEXSITE_API_URL - Override the API base URL (default: https://cli-api.flexsite.io/v1)
• FLEXSITE_SSH_IDENTITY - Use a specific private key for ssh/drush/wp instead of the managed ~/.flexsite/id_ed25519
• FLEXSITE_SSH_HOST_KEY - Pin the gateway host public key (skips first-use trust prompt)
• FLEXSITE_SSH_HOST / FLEXSITE_SSH_PORT - Override the gateway host/port (defaults: ssh.flexsite.io / 2222)

Token Scopes

When creating a personal access token, you can limit its permissions:

| Scope | Description | |-------|-------------| | backup:read | Download database backups | | backup:create | Create new database backups | | files:read | Download files backups | | files:create | Create new files backups | | drush:execute | Execute Drush/WP-CLI commands remotely (SSH gateway) | | ssh:access | Open a read-only inspection shell (SSH gateway) | | projects:read | List projects | | environments:read | List environments |

Note: The flexsite composer commands work locally and do not require authentication or any token scopes.

License

MIT