scp-next 1.0.15 → 1.0.17

package/README.md

@@ -17,7 +17,7 @@
 
 `scp-next` is an SCP-style command-line tool and library for secure file transfers over SSH.
 It uses SFTP internally through `ssh2-sftp-client` instead of implementing SCP or SFTP protocols manually.
-Developer documentation is available at <https://chengchuu.github.io/scp-next/>.
+Developer documentation is available at [GitHub Pages](https://chengchuu.github.io/scp-next/).
 
 ## Contents
 
@@ -51,7 +51,7 @@ npm install scp-next
 
 ## Quick Start
 
-Upload with password authentication:
+Upload a directory:
 
 ```bash
 scp-next upload ./dist /var/www/example \
@@ -61,15 +61,18 @@ scp-next upload ./dist /var/www/example \
   --recursive
 ```
 
-Download with private-key authentication:
+Download a file:
 
 ```bash
 scp-next download /var/log/example.log ./logs/example.log \
   --host your-host \
   --username your-username \
-  --private-key-file ~/.ssh/id_ed25519
+  --password your-password
 ```
 
+Password arguments are convenient, but they may be exposed through shell history and process listings.
+Prefer `SCP_NEXT_PASSWORD`, SSH agents, or protected private-key files for shared or production environments.
+
 Use the library:
 
 ```ts
@@ -78,7 +81,7 @@ import { upload } from "scp-next";
 await upload({
   host: process.env.SCP_NEXT_HOST,
   username: process.env.SCP_NEXT_USERNAME,
-  privateKeyFile: process.env.SCP_NEXT_PRIVATE_KEY_FILE,
+  password: process.env.SCP_NEXT_PASSWORD,
   localPath: "./dist",
   remotePath: "/var/www/example",
   recursive: true,
@@ -108,21 +111,66 @@ Destination paths follow familiar `cp`/`scp` behavior. If the destination exists
 
 ### Upload Examples
 
+Preview a recursive deploy before connecting:
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host your-host \
+  --username your-username \
+  --password your-password \
+  --recursive \
+  --dry-run
+```
+
+Deploy with overwrite and verbose diagnostics:
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host your-host \
+  --username your-username \
+  --password your-password \
+  --recursive \
+  --overwrite \
+  --verbose
+```
+
+Use an encrypted private key:
+
 ```bash
 scp-next upload ./dist /var/www/example \
   --host your-host \
   --username your-username \
   --private-key-file ~/.ssh/id_ed25519 \
+  --passphrase your-passphrase \
   --recursive
 ```
 
 ### Download Examples
 
+Download a remote directory recursively:
+
+```bash
+scp-next download /var/log/example ./logs/example \
+  --host your-host \
+  --username your-username \
+  --password your-password \
+  --recursive
+```
+
+Download and overwrite an existing local file:
+
 ```bash
 scp-next download /var/log/example.log ./logs/example.log \
   --host your-host \
   --username your-username \
-  --private-key-file ~/.ssh/id_ed25519
+  --password your-password \
+  --overwrite
+```
+
+Run a configured download job:
+
+```bash
+scp-next run download-logs --config ./scp-next.config.json
 ```
 
 ### CLI Options
@@ -159,7 +207,7 @@ import { upload } from "scp-next";
 await upload({
   host: process.env.SCP_NEXT_HOST,
   username: process.env.SCP_NEXT_USERNAME,
-  privateKeyFile: process.env.SCP_NEXT_PRIVATE_KEY_FILE,
+  password: process.env.SCP_NEXT_PASSWORD,
   localPath: "./dist",
   remotePath: "/var/www/example",
   recursive: true,
@@ -176,7 +224,7 @@ async function main() {
   await download({
     host: process.env.SCP_NEXT_HOST,
     username: process.env.SCP_NEXT_USERNAME,
-    privateKeyFile: process.env.SCP_NEXT_PRIVATE_KEY_FILE,
+    password: process.env.SCP_NEXT_PASSWORD,
     remotePath: "/var/log/example.log",
     localPath: "./logs/example.log"
   });
@@ -196,7 +244,7 @@ import { createClient } from "scp-next";
 const client = createClient({
   host: process.env.SCP_NEXT_HOST,
   username: process.env.SCP_NEXT_USERNAME,
-  privateKeyFile: process.env.SCP_NEXT_PRIVATE_KEY_FILE
+  password: process.env.SCP_NEXT_PASSWORD
 });
 
 try {
@@ -234,12 +282,10 @@ await upload({
 
 ### Configuration Files
 
-`scp-next` searches for these files in the current directory:
+Use `scp-next.config.json` in the current directory. `scp-next` also auto-detects these rc-style filenames: `.scp-nextrc`, `.scp-nextrc.json`.
 
 ```text
 scp-next.config.json
-.scp-nextrc
-.scp-nextrc.json
 ```
 
 Use `--config` for an explicit path:
@@ -264,7 +310,7 @@ Example:
     "host": "your-host",
     "port": 22,
     "username": "your-username",
-    "privateKeyFile": "~/.ssh/id_ed25519"
+    "password": "your-password"
   },
   "transfer": {
     "recursive": true,
@@ -275,6 +321,8 @@ Example:
 }
 ```
 
+Do not commit configuration files containing real passwords. Prefer `SCP_NEXT_PASSWORD` or another protected secret source for shared repositories and deployment environments.
+
 Configuration file options:
 
 | Key              | Description                                                         |
@@ -298,7 +346,7 @@ and `hostFingerprint` are also supported for simple configuration files, but `se
       "host": "your-host-a",
       "port": 22,
       "username": "your-username-a",
-      "privateKeyFile": "~/.ssh/id_ed25519"
+      "password": "your-password-a"
     },
     "staging": {
       "host": "your-host-b",
@@ -324,7 +372,7 @@ Jobs use `source` and `destination`; the `operation` determines which path is lo
     "production": {
       "host": "your-host",
       "username": "your-username",
-      "privateKeyFile": "~/.ssh/id_ed25519"
+      "password": "your-password"
     }
   },
   "jobs": {
@@ -373,7 +421,7 @@ Bash:
 ```bash
 export SCP_NEXT_HOST="your-host"
 export SCP_NEXT_USERNAME="your-username"
-export SCP_NEXT_PRIVATE_KEY_FILE="$HOME/.ssh/id_ed25519"
+export SCP_NEXT_PASSWORD="your-password"
 scp-next upload ./dist /var/www/example --recursive
 ```
 
@@ -382,7 +430,7 @@ PowerShell:
 ```powershell
 $env:SCP_NEXT_HOST = "your-host"
 $env:SCP_NEXT_USERNAME = "your-username"
-$env:SCP_NEXT_PRIVATE_KEY_FILE = "$HOME\.ssh\id_ed25519"
+$env:SCP_NEXT_PASSWORD = "your-password"
 scp-next upload .\dist /var/www/example --recursive
 ```
 
@@ -454,7 +502,7 @@ try {
   await upload({
     host: process.env.SCP_NEXT_HOST,
     username: process.env.SCP_NEXT_USERNAME,
-    privateKeyFile: process.env.SCP_NEXT_PRIVATE_KEY_FILE,
+    password: process.env.SCP_NEXT_PASSWORD,
     localPath: "./dist",
     remotePath: "/var/www/example"
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scp-next",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "A SCP CLI and library for secure SSH file transfers using SFTP.",
   "type": "module",
   "main": "./dist/index.cjs",