scp-next 1.0.1 → 1.0.3

package/README.md

@@ -1,20 +1,31 @@
 # scp-next
 
-`scp-next` is a SCP command-line tool and library for secure file transfers over SSH.
-The package uses SFTP internally through `ssh2-sftp-client` instead of implementing SCP or SFTP protocols manually.
+[![npm version][npm-image]][npm-url]
+[![license][license-image]][license-url]
+[![node version][node-image]][npm-url]
+[![module type][module-image]][npm-url]
+
+[npm-image]: https://img.shields.io/npm/v/scp-next
+[npm-url]: https://npmjs.org/package/scp-next
+[license-image]: https://img.shields.io/npm/l/scp-next
+[license-url]: https://github.com/chengchuu/scp-next
+[node-image]: https://img.shields.io/node/v/scp-next
+[module-image]: https://img.shields.io/badge/module-ESM%20%2B%20CJS-blue
+
+`scp-next` is an SCP-style command-line tool and library for secure file transfers over SSH.
+The package uses SFTP internally through `ssh2-sftp-client` instead of implementing SCP or
+SFTP protocols manually.
 
 ## Features
 
-- Upload and download files.
-- Upload and download directories recursively.
-- CLI usage with `<source> <destination>` operands.
-- ESM `import` and CommonJS `require` library usage.
-- Reusable transfer client.
+- Upload and download files or directories recursively.
+- CLI usage with clear `<source> <destination>` operands.
+- ESM `import` and CommonJS `require` support.
 - JSON configuration files, named profiles, and configured jobs.
-- Environment-variable based credentials.
+- Environment-variable-based credentials.
 - Dry-run mode, progress callbacks, timeouts, overwrite control, and destination directory creation.
-- Typed errors with stable error codes.
 - Secret redaction for passwords, passphrases, and private-key contents.
+- Reusable transfer client.
 
 ## Installation
 
@@ -31,14 +42,6 @@ scp-next download <source> <destination> [options]
 scp-next run <job> [source] [destination] [options]
 ```
 
-Terminology is intentionally consistent:
-
-```text
-Operation  Source  Destination
-Upload     Local   Remote
-Download   Remote  Local
-```
-
 CLI commands use `<source> <destination>`. Programmatic upload and download APIs use
 `localPath` and `remotePath`.
 
@@ -53,6 +56,20 @@ scp-next upload ./dist /var/www/example \
   --create-directories
 ```
 
+Password authentication:
+
+```bash
+scp-next upload ./dist /var/www/example \
+  --host example.com \
+  --username deploy \
+  --password "your-password" \
+  --recursive
+```
+
+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.
+
 ## Download Examples
 
 ```bash
@@ -65,30 +82,26 @@ scp-next download /var/log/example.log ./logs/example.log \
 
 ## CLI Options
 
-```text
---host
---port
---username
---password
---private-key
---private-key-file
---passphrase
---config
---profile
---recursive
---overwrite
---create-directories
---dry-run
---timeout
---verbose
---quiet
---help
---version
-```
-
-Avoid `--password` when possible because command-line arguments may be visible in shell
-history and process listings. Prefer environment variables, SSH agents, or protected
-private-key files.
+| Option                                | Description                                                            |
+| ------------------------------------- | ---------------------------------------------------------------------- |
+| `--host <host>`                       | SSH server host.                                                       |
+| `--port <port>`                       | SSH server port. Defaults to `22`.                                     |
+| `--username <username>`               | SSH username.                                                          |
+| `--password <password>`               | SSH password. Prefer environment variables, SSH agents, or key files.  |
+| `--private-key <privateKey>`          | Private-key content. Redacted from logs and errors.                    |
+| `--private-key-file <privateKeyFile>` | Private-key file path. Supports `~` expansion.                         |
+| `--passphrase <passphrase>`           | Passphrase for an encrypted private key.                               |
+| `--config <path>`                     | Explicit configuration file path.                                      |
+| `--profile <name>`                    | Named server profile from the configuration file.                      |
+| `--recursive`                         | Transfer directories recursively.                                      |
+| `--overwrite`                         | Allow replacing existing destination files.                            |
+| `--create-directories`                | Create missing destination directories when supported.                 |
+| `--dry-run`                           | Resolve and validate the operation without connecting or transferring. |
+| `--timeout <milliseconds>`            | Connection and operation timeout in milliseconds.                      |
+| `--verbose`                           | Print non-sensitive diagnostic details.                                |
+| `--quiet`                             | Disable progress and non-error output.                                 |
+| `--help`                              | Show command help.                                                     |
+| `--version`                           | Show the package version.                                              |
 
 ## Configuration Files
 
@@ -355,7 +368,13 @@ non-sensitive context.
 import { AuthenticationError, upload } from "scp-next";
 
 try {
-  await upload({ localPath: "./dist", remotePath: "/var/www/example" });
+  await upload({
+    host: process.env.SCP_NEXT_HOST,
+    username: process.env.SCP_NEXT_USERNAME,
+    privateKeyFile: process.env.SCP_NEXT_PRIVATE_KEY_FILE,
+    localPath: "./dist",
+    remotePath: "/var/www/example"
+  });
 } catch (error) {
   if (error instanceof AuthenticationError) {
     console.error("SSH authentication failed.");

package/package.json

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