SCP-style commands with SFTP safety and a typed API.

Features

Quick Start

scp-next upload ./dist /var/www/example \
  --host your-host \
  --username your-username \
  --password your-password \
  --recursive

scp-next download /var/log/example.log ./logs/example.log \
  --host your-host \
  --username your-username \
  --password your-password

import { upload } from "scp-next";

await upload({
  host: process.env.SCP_NEXT_HOST,
  username: process.env.SCP_NEXT_USERNAME,
  password: process.env.SCP_NEXT_PASSWORD,
  localPath: "./dist",
  remotePath: "/var/www/example",
  recursive: true,
  overwrite: true
});

CLI Usage

Commands use the standard operand order: <source> <destination> [options].

scp-next upload ./dist /var/www/example \
  --host your-host \
  --username your-username \
  --password your-password \
  --recursive

scp-next download /var/log/example.log ./logs/example.log \
  --host your-host \
  --username your-username \
  --password your-password

CLI Options

--timeout maps to the SSH readyTimeout. It controls how long to wait for the connection handshake, not the duration of each file transfer or the whole transfer run.

Library API

import { upload } from "scp-next";

await upload({
  host: process.env.SCP_NEXT_HOST,
  username: process.env.SCP_NEXT_USERNAME,
  password: process.env.SCP_NEXT_PASSWORD,
  localPath: "./dist",
  remotePath: "/var/www/example",
  recursive: true,
  overwrite: true
});

import { createClient } from "scp-next";

const client = createClient({
  host: process.env.SCP_NEXT_HOST,
  username: process.env.SCP_NEXT_USERNAME,
  password: process.env.SCP_NEXT_PASSWORD
});

try {
  await client.connect();
  await client.upload("./dist", "/var/www/example", {
    recursive: true
  });
} finally {
              await client.close();
}

import { readFile } from "node:fs/promises";

import { upload, type ScpNextConfig } from "scp-next";

const config = JSON.parse(
  await readFile(new URL("./scp-next.config.json", import.meta.url), "utf8")
) as ScpNextConfig;

await upload({
  ...config.server,
  ...config.transfer,
  localPath: "./dist",
  remotePath: "/var/www/example"
});

Library Options

Advanced Usage

`scp-next` supports JSON configuration files, named profiles, reusable jobs, and environment variables. Explicit CLI input always wins.

{
  "server": {
    "host": "your-host",
    "port": 22,
    "username": "your-username",
    "password": "your-password"
  },
  "transfer": {
    "recursive": true,
    "overwrite": true,
    "createDirectories": true,
    "timeout": 30000
  }
}

{
  "jobs": {
    "deploy": {
      "operation": "upload",
      "profile": "production",
      "source": "./dist",
      "destination": "/var/www/example",
      "recursive": true
    }
  }
}

scp-next upload ./dist /var/www/example \
  --config ./deploy/scp-next.json

scp-next upload ./dist /var/www/example \
  --config ./scp-next.config.json \
  --profile production

Configuration File Options

Use scp-next.config.json in the current directory. scp-next also auto-detects rc-style filenames: .scp-nextrc and .scp-nextrc.json.

Server Fields

Transfer and Job Fields

Environment Variables

Precedence

1. Explicit CLI options
2. Positional CLI operands
3. Environment variables
4. Selected configuration profile
5. Root-level configuration values
6. Configured job values
7. Internal defaults

User Guides

Read the versioned user guides for a fuller introduction to installation, CLI transfers, configuration files, credential handling, library usage, and onboarding.

Security

• Transfers use SFTP through `ssh2-sftp-client`; normal transfers do not run remote shell commands.
• Passwords, passphrases, private-key contents, and tokens are redacted from logs and errors.
• Host verification is not silently disabled. Configure known hosts or a host fingerprint when required.
• Local paths use OS-aware Node path behavior; remote paths preserve POSIX `/` separators.
• Dry-run mode resolves and validates a transfer plan without connecting or modifying files.

Architecture

For deeper implementation notes, read docs/ARCHITECTURE.md.