Splinter FTP Client

A command-line FTP client that lets you define reusable upload, download, and server-delete actions in a .splinter file.

Full documentation: https://splinter.seremtitus.co.ke/

Installation

npm i -g splinter-ftp

Requires Node.js 22 or later.

Quick Start

# Save credentials (interactive menu)
splinter logins

# Or open the interactive remote browser
splinter

# Navigate to project and add actions
cd my-project
splinter add            # add an upload action
splinter add            # add another action

# Run uploads
splinter up

# Run downloads
splinter down

# Run server deletes
splinter delete

Commands

| Command | Description | |---------|-------------| | splinter | Open the TUI remote file browser | | splinter logins | Manage FTP connection credentials (add, list, delete) | | splinter add | Interactively add an action to the .splinter file | | splinter delete [--verbose] [--concurrency n] | Execute all server delete actions defined in .splinter | | splinter remove | Interactively remove actions from the .splinter file | | splinter up [--verbose] [--concurrency n] | Execute all upload actions defined in .splinter | | splinter down [--verbose] [--concurrency n] | Execute all download actions defined in .splinter | | splinter history [--verbose] [--concurrency n] | Browse folders registered via splinter commands |

By default, upload, download, and delete actions use CPU cores - 2 concurrent FTP connections, with a minimum of 1. Add --concurrency 4 or -c 4 to override it. Each worker uses its own FTP session, following Cyberduck's concurrent transfer model so control connections are not shared or locked.

Default output uses a single updating overall progress line, such as [############--------] 12/28 60% 240 KB/s 75% /path/file.txt. Skipped paths are summarized on the completion line, for example Upload complete. Skipped 1. Add --verbose or -v to splinter up, splinter down, splinter delete, or splinter history to print one line for every uploaded, downloaded, skipped, or deleted path. Recursive filters are matched relative to the action source and only exclude matching paths from the current action.

TUI Browser

Run splinter with no command to open the Ink-powered terminal UI. If the current folder has a .splinter file with a valid login, Splinter connects to that server immediately. Otherwise it opens a connection picker showing saved aliases and host URLs, with an option to add credentials. Credentials added in the TUI are saved globally in ~/.splinter/credentials.json.

Inside the remote browser, use up/down arrows or the mouse to select files and folders. Press right arrow or Enter, or double-click a folder, to open it; press left arrow to go to the parent folder. Press u to upload into the current remote folder, d to download the selected file or folder, x to delete the selected remote path, and s to choose another connection. Transfer forms let you set the local path, overwrite behavior, and comma-separated exclusion filters. Forms and confirmations use Enter to continue and Esc to cancel, with no on-screen buttons. These actions are session-only and never modify .splinter. Press Esc twice to exit.

.splinter File Format

The .splinter file is a JSON file in your project directory that holds the login alias and an array of actions:

{
  "login": "prod",
  "actions": [
    {
      "type": "up",
      "source": "./dist",
      "to": "/var/www/html",
      "recursive": true,
      "overwrite": true,
      "filter": ["node_modules/**", "*.map"],
      "command": "npm run build"
    },
    {
      "type": "down",
      "source": "/backups/data",
      "to": "./downloads",
      "recursive": true,
      "overwrite": false,
      "filter": ["cache/"]
    },
    {
      "type": "delete",
      "source": "/tmp/build-artifacts",
      "recursive": true,
      "overwrite": true,
      "filter": ["keep/"]
    }
  ]
}

Fields

| Field | Type | Description | |-------|------|-------------| | login | string | Alias of saved credentials to use | | type | "up"|"down"|"delete" | Action to execute | | source | string | Source path for transfers, or remote target for delete | | to | string | Destination path for up/down actions; omitted for delete actions | | recursive | boolean | Recurse into directories | | overwrite | boolean | Overwrite existing files for up/down actions | | filter | string[] | Optional glob patterns to skip, such as node_modules/**, *.map, or cache/ | | command | string | Optional shell command run before the transfer |

Missing .splinter keys are repaired with defaults when the file is loaded. Invalid JSON is backed up next to the original file and replaced with a valid default file.

Credentials

Credentials are stored globally in ~/.splinter/credentials.json and managed via splinter logins.