Splinter is a command-line FTP client that lets you define reusable upload, download, and delete actions in a `.splinter` file. Store credentials once with splinter logins, define actions with splinter add, then run splinter up or splinter down or splinter delete to execute all actions of same type. Run plain splinter to browse the remote file system in a terminal UI.

Installation

npm i -g splinter-ftp

Requires Node.js

splinter logins

Opens an interactive menu to manage FTP connection credentials. You can add, list, and delete logins. Credentials are stored globally in ~/.splinter/credentials.json.

# Interactive menu to manage credentials
splinter logins

# Shows saved logins and lets you:
# 1. Add new login
# 2. Delete a login
# 3. Back

splinter add

Interactively add an action to the .splinter file in the current directory. You will be prompted for the action type (up/down/delete), source and destination paths, whether to recurse into directories, whether to overwrite existing files, exclusion filters, and which saved login to use.

splinter add

splinter remove

Interactively remove configured actions from the .splinter file. Shows all current actions and lets you pick one to remove, or type all to clear everything. If no actions remain, the .splinter file is deleted.

splinter remove

# Current actions:
#   1. [up] ./dist -> /var/www/html
#   2. [delete] /tmp/build-artifacts
# Action number to remove (or 'all'): 1
# Action removed. 1 action(s) remaining.

splinter up / splinter down / splinter delete

Execute upload, download, or server-delete actions defined in the .splinter file. The tool connects to the FTP server using the login alias stored in the file and runs each matching action. Recursive actions match filters relative to the action source. Transfers use CPU cores - 2 concurrent FTP connections by default, with one FTP session per worker. Add --concurrency 4to override it. Default progress stays on one updating line, like [############--------] 12/28 60% 240 KB/s 75% /path/file.txt.--verbose to print every uploaded, downloaded, skipped, or deleted path.

splinter up
splinter up --verbose
splinter up --concurrency 4

splinter down
splinter down --verbose
splinter down --concurrency 4

splinter delete
splinter delete --verbose
splinter delete --concurrency 4

splinter all

Execute every action in the current .splinter file, one at a time in the order it is listed. Upload, download, and server-delete actions can be interleaved, and each action finishes before the next begins. The command supports the same --verbose and --concurrency options as the individual action commands.

splinter all
splinter all --verbose
splinter all --concurrency 4

splinter history

Browse folders that have been registered via splinter add, splinter up, splinter down, or splinter delete. Folders are listed newest-first, 5 at a time. Select one to run uploads, downloads, or deletes on that folder. Add --verbose or --concurrency 4 to pass those options into the selected action.

splinter history
splinter history --verbose
splinter history --concurrency 4

# Recent folders (page 1/2):
#   1. D:\Projects\site  (3 actions, just now)
#   2. D:\Projects\blog  (1 action, 2h ago)
#   3. D:\Projects\app   (5 actions, yesterday)
#   4. D:\Projects\docs  (2 actions, 3d ago)
#   5. D:\Projects\old   (1 action, 1w ago)
# Select 1-5, 'n' next, 'q' quit:

Splinter Terminal UI

Running splinter with no command opens the terminal UI. If the current folder has a .splinter file with a valid login alias, Splinter connects directly to that server. Otherwise, it shows a centered credential picker with saved aliases, host URLs, and an add-credential flow. TUI uploads, downloads, and deletes are session-only and never write actions to .splinter.

splinter

# Opens the remote file browser.
# If .splinter has a valid login, connects directly.
# Otherwise, choose or add credentials first.

.splinter File

The .splinter file is a JSON file in your project directory. It holds the login alias and an array of actions. Missing keys are repaired with defaults when loaded, and invalid JSON is backed up before a default file is recreated.

{
  "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/"]
    }
  ]
}

Filter Patterns

Filters are matched against paths relative to the action source. For uploads, that means paths inside the local source folder. For downloads and deletes, that means paths inside the remote source folder. A filter only excludes the matching file or folder from the current action; it does not delete, clean, or otherwise modify that path.

[
  "404/index.html",
  "cache/",
  "node_modules/**",
  "*.map",
  "_next/static/chunks/*.js",
  "thumbs.db"
]

Example Workflow

# Save credentials (interactive menu)
splinter logins

# 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

# Remove configured actions
splinter remove