Flowscripter IO CLI Flowscripter

Use this command to install Flowscripter IO CLI with WinGet:

winget install --id=Flowscripter.flowscripter-io-cli -e

CLI for the pluggable-io-framework

flowscripter-io-cli

> CLI for the > pluggable-io-framework, > built on > dynamic-cli-framework

Installation

NOTE: The binaries are 10's of megabytes in size as the entire Bun runtime is included.

MacOS

Via Homebrew:

brew install flowscripter/tap/flowscripter-io-cli

Linux

In a terminal:

curl -fsSL https://raw.githubusercontent.com/flowscripter/flowscripter-io-cli/main/script/install.sh | sh

Windows

Via Winget:

winget install Flowscripter.flowscripter-io-cli

Manual Install

You can download and extract the binary zip files from the releases page.

Locations

Every command addresses data through a location argument: --source and --dest for copy/move, and --location for the other commands. A location has a protocol and one group of fields per installed protocol:

--location.protocol=file selects the protocol. The allowed values are the protocols of the installed provider plugins.
--location.file.path=/data and the other fields of the selected protocol are taken from that protocol's provider plugin, and are validated against it.
For file (and other protocols with folders), a location with a filename addresses one file, one with a pattern (a glob such as *.txt) addresses the matching files in path, and one with neither addresses the whole path folder.

flowscripter-io-cli --help lists the fields of every installed protocol.

Commands

list --location [--recursive] [--regex] - list a folder, or the files matching a pattern location, one JSON line per item
get-properties --location - print a file or folder's properties as JSON
set-properties --location [--last-modified] [--content-type] [--properties..] - set properties: last modified time and content type apply to every protocol, and --properties holds one group per protocol for its own settable properties (e.g. --properties.file.mode=384)
delete --location - delete a file or folder
copy --source --dest [--payload-kind] - copy a file, a folder, or the files matching a pattern, using a direct provider copy when possible, with a progress bar for a single file. Prints the negotiated transfer path, e.g. path: file/js -> file/js, direct
move --source --dest [--payload-kind] - move, with the same behaviour as copy
hash --location [--algorithm] [--payload-kind] - hash a file by reading its stream directly, outside the framework's transfer path. --algorithm is one of sha1, sha256 (the default, using a native hasher), sha384, sha512 or md5

Common behaviour:

--payload-kind is auto (the default, letting the registry choose), js or native. An unavailable kind fails with the kinds that are installed.
During list, copy, move or hash, the first Ctrl-C stops gracefully and reports the result as stopped, and a second Ctrl-C cancels.
Operations a protocol does not support (e.g. list over https) fail with a "not supported by protocol" error.
Any required argument omitted on the command line is prompted for interactively, via dynamic-cli-framework's ArgumentPrompterService.

Provider Plugins

This package has no dependency on any provider plugin. Install one or more through the CLI's own plugin management (provided by dynamic-cli-framework's plugin commands). They are discovered at startup through dynamic-plugin-framework's NpmPluginRepository, and several protocols, or several implementations of one protocol, can be installed side by side:

flowscripter-io-cli plugin:add @flowscripter/io-plugin-filesystem

Usage

Once installed (see Installation):

flowscripter-io-cli plugin:add @flowscripter/io-plugin-filesystem
flowscripter-io-cli list --location.protocol=file --location.file.path=.
flowscripter-io-cli copy \
  --source.protocol=file --source.file.path=. --source.file.filename=a.txt \
  --dest.protocol=file --dest.file.path=. --dest.file.filename=b.txt
flowscripter-io-cli copy \
  --source.protocol=file --source.file.path=. --source.file.pattern='*.txt' \
  --dest.protocol=file --dest.file.path=backup
flowscripter-io-cli hash --location.protocol=file --location.file.path=. \
  --location.file.filename=a.txt --algorithm sha256

Development

Install dependencies:

bun install

Test:

bun test

Format:

bunx oxfmt

Lint:

bunx oxlint index.ts src/ tests/

Functional Tests

Refer to functional_tests/README.md

Documentation

Refer to pluggable-io-framework, pluggable-io-framework-api and io-plugin-filesystem for the contracts and orchestration this CLI is built on.

License

MIT © Flowscripter