
<!-- documentation/commands - This documentation describes the various supported terminal commands and is automatically generated from `lib/terminal/utilities/commands_documentation.ts`. -->

# Share File Systems - Command Documentation
This documentation is also available interactively at your finger tips using the command: `share commands`.  **Please do not edit this file as it is written by the build process.**

## agent_data
Lists agent data.

### Examples
1. `share agent_data`
   - Lists all agent data.
1. `share agent_data device`
   - Lists all device type agent data.
1. `share agent_data user`
   - Lists all user type agent data.
1. `share agent_data "desktop computer"`
   - Lists any agent whose names contain the search string
1. `share agent_data "16f07e8ed7225f07912da48e0d51308e8fbf9dafc89d8accaa58abc1da8a2832a046082bfc2534eb4933a00bd673019cb90437c8a94cc0d0adaf9cff40c5083b"`
   - Outputs data for the matching hash string, if any.  The hash must be composed of 128 characters only composed of only 0-9 and lower case a-f.

## agent_online
Allows testing connectivity to remote agents.  Think of this as an alternative to ping where specified port, address, and protocol are tested for the agents specified.

### Examples
1. `share agent_online a5908e8446995926ab2dd037851146a2b3e6416dcdd68856e7350c937d6e92356030c2ee702a39a8a2c6c58dac9adc3d666c28b96ee06ddfcf6fead94f81054e`
   - This will test a connection to the specified agent.
1. `share agent_online list`
   - Specifying the parameter 'list' will output a list of all agent hashes, names, and IP addresses by agent type.
1. `share agent_online device`
   - An argument of 'device' will test connectivity on each device agent.
1. `share agent_online user`
   - An argument of 'user' will test connectivity on each user agent.
1. `share agent_online all`
   - An argument of 'all' will run connectivity tests on all stored agents.

## base64
Convert a file or string into a base64 encoding.

### Examples
1. `share base64 encode string:"my string to encode"`
   - Converts the provided string into a base64 encoding.
1. `share base64 encode path/to/file`
   - Converts the provided file into a base64 encoding.
1. `share base64 encode http://file.from.internet.com`
   - Reads a file from a URI and outputs a base64 encoding.
1. `share base64 decode string:"a big base64 string"`
   - Decodes base64 strings into decoded output.

## build
Rebuilds the application.

### Examples
1. `share build`
   - Compiles from TypeScript into JavaScript and puts libraries together.
1. `share build force_certificate`
   - Creates and installs new certificates even if already installed.
1. `share build force_port`
   - Forces execution of the setcap utility in Linux to allow executing services on reserved ports.
1. `share build force_port type_validate`
   - Forces TypeScript type validation as part of the build process immediately prior to the compile step.

## certificate
Creates an HTTPS certificate and saves it in the local "certificate" directory.

### Examples
1. `share certificate location:"/file/path/to/save"`
   - By default three certificates and corresponding keys are created: root, intermediate, and server certificates. Provide a file system path of where to save certificates. If no path is provided no certificates will be written.
1. `share certificate location:"/file/path/to/save" self-sign`
   - The "self-signed" argument instead creates a self-signed root certificate without creating the intermediate or server certificates.
1. `share certificate location:"/file/path/to/save" days:365`
   - Specify the number of days until the certificate expires. The value must be an integer. The default value is 16384.
1. `share certificate location:"/file/path/to/save" intermediate-fileName:"certificate"`
   - The file name of the intermediate certificate and supporting files. The default value is "share-file-ca" if no name is provided. Do not provide a file extension in the file name value. An intermediate certificate can sign other certificates but is not self-signed.
1. `share certificate location:"/file/path/to/save" intermediate-domain:"my-domain"`
   - Specify a certificate domain. This is optional in create mode and defaults to "share-file-ca". This argument is required in remove mode on Windows as only certificates with a matching domain will be removed.
1. `share certificate location:"/file/path/to/save" organization:"my-domain"`
   - Specify a certificate org value by providing an argument beginning 'organization:'. This is optional in create mode and defaults to "share-file". This argument is required in remove mode on Windows as certificates with a matching org value will be removed.
1. `share certificate location:"/file/path/to/save" root-fileName:"certificate"`
   - The file name of the self signed authority certificate and supporting files. The default value is "share-file-root" if no name is provided. Do not provide a file extension in the file name value. This is not used on self signed certificate mode.
1. `share certificate location:"/file/path/to/save" root-domain:"my-domain"`
   - Specify a self-signed root certificate authority domain. This is optional and defaults to "share-file-root". This argument is ignored for certificates in self sign mode or if mode is remove.
1. `share certificate location:"/file/path/to/save" server-fileName:"certificate"`
   - The file name of a signed certificate and supporting files that cannot sign other certificates. The default value is "share-file" if no name is provided. Do not provide a file extension in the file name value.
1. `share certificate location:"/file/path/to/save" server-domain:"my-domain"`
   - Specify a certificate domain. This is optional in create mode and defaults to "share-file". This argument is required in remove mode on Windows as only certificates with a matching domain will be removed.

## commands
List all supported commands to the console or examples of a specific command.

### Examples
1. `share commands`
   - Lists all commands and their definitions to the shell.
1. `share commands directory`
   - Details the mentioned command with examples, which in this case is the 'directory' command.
1. `share commands all`
   - Specifying 'all' will output verbose documentation and code examples for all supported commands.

## copy
Copy files or directories from one location to another on the local file system.

### Examples
1. `share copy source/file/or/directory destination/path`
   - Copies the file system artifact at the first address to the second address.
1. `share copy "C:\Program Files" destination\path`
   - Quote values that contain non-alphanumeric characters.
1. `share copy source/file/or/directory destination/path replace`
   - The "replace" argument tells the copy command to overwrite any files of the same name at the destination location. If this argument is absent files are renamed to prevent a collision.
1. `share copy source destination ignore [build, .git, node_modules]`
   - Exclusions are permitted as a comma separated list in square brackets following the ignore keyword.
1. `share copy source destination ignore[build, .git, node_modules]`
   - A space between the 'ignore' keyword and the opening square brace is optional.
1. `share copy ../sparser ../sparserXX ignore [build, .git, node_modules]`
   - Exclusions are relative to the source directory.

## directory
Traverses a directory in the local file system and generates a list.  If a source is not provided the current working directory is used.

### Examples
1. `share directory source:"my/directory/path"`
   - Returns an array where each index is an array of [absolute path, type, parent index, file count, stat]. Type can refer to 'file', 'directory', or 'link' for symbolic links.  The parent index identify which index in the array is the objects containing directory and the file count is the number of objects a directory type object contains.
1. `share directory source:"my/directory/path" depth:9`
   - The depth of child directories to traverse. The default value of 0 applies full recursion.
1. `share directory source:"my/directory/path" symbolic`
   - Identifies symbolic links instead of the object the links point to
1. `share directory source:"my/directory/path" ignore [.git, node_modules, "program files"]`
   - Sets an exclusion list of things to ignore.
1. `share directory source:"my/path" typeof`
   - Returns a string describing the artifact type.
1. `share directory source:"my/directory/path" mode:"array"`
   - Returns an array of strings where each index is an absolute path.
1. `share directory source:"my/path" mode:"hash"`
   - Includes a SHA512 hash in the output for each file system object of type 'file'.
1. `share directory source:"my/directory/path" mode:"list"`
   - Writes a list of file system artifacts, one per line, to the shell.
1. `share directory source:"my/directory/path" search:"any string"`
   - Returns results in the default format, but only containing artifacts containing the search token. If the 'search' argument is not provided the search function will not be applied.
1. `share directory source:"my/directory/path" relative`
   - The relative argument provide relative paths from the source path instead of absolute paths.
1. `share directory source:"my/directory/path" sort:"file-system-type"`
   - Sort the output according to a supported sorting convention. The argument must begin with 'sort:' followed by a support value that may or may not be quoted.  Supported values are: 'alphabetically-ascending', 'alphabetically-descending', 'file-extension', 'file-modified-ascending', 'file-modified-descending', 'file-system-type', 'size-ascending', 'size-descending'

## firewall
Opens the firewall for this application.  Currently only supporting Windows Defender Firewall.

### Examples
1. `share firewall`
   - Adds necessary allowances to the firewall specific for this application.

## get
Retrieve a resource via an absolute URI.

### Examples
1. `share get http://example.com/file.txt`
   - Gets a resource from the web and prints the output to the shell.
1. `share get http://example.com/file.txt path/to/file`
   - Get a resource from the web and writes the resource as UTF8 to a file at the specified path.

## hash
Generate a SHA512 hash of a file or a string.

### Examples
1. `share hash path/to/file`
   - Prints a SHA512 hash to the shell for the specified file's contents in the local file system.
1. `share hash verbose path/to/file`
   - Prints the hash with file path and version data.
1. `share hash string:"I love kittens."`
   - Hash an arbitrary string directly from shell input.
1. `share hash https://prettydiff.com/`
   - Hash a resource from the web.
1. `share hash path/to/directory`
   - Directory hash recursively gathers all descendant artifacts and hashes the contents of each of those items that are files, hashes the paths of directories, sorts this list, and then hashes the list of hashes.
1. `share hash path/to/directory list`
   - Returns a JSON string of an object where each file, in absolutely path, is a key name and its hash is the key's value.
1. `share hash file/system/path sha3-512`
   - The algorithm argument allows a choice of hashing algorithm. Supported values: 'blake2d512', 'blake2s256', 'sha3-224', 'sha3-256', 'sha3-384', 'sha3-512', 'sha384', 'sha512', 'sha512-224', 'sha512-256', 'shake128', 'shake256'
1. `share hash file/system/path base64`
   - By default hash values are generated as strings in hexadecimal notation, but some operations may require base64 strings. Supported values: 'base64', 'hex'

## lint
Use ESLint against all JavaScript files in a specified directory tree.

### Examples
1. `share lint ../tools`
   - Lints all the JavaScript files in that location and in its subdirectories.
1. `share lint`
   - Specifying no location defaults to the Share File Systems application directory.
1. `share lint ../tools ignore [node_modules, .git, test, units]`
   - An ignore list is also accepted if there is a list wrapped in square braces following the word 'ignore'.

## mkdir
Recursively creates a directory structure.  For example if 'my/new/path` were to be created but parent 'my' doesn't exist this command will create all three directories, but it will not alter or overwrite any artifacts already present. Relative paths are relative to the terminal's current working directory.

### Examples
1. `share mkdir my/path/to/create`
   - This example would create directories as necessary to ensure the directory structure 'my/path/to/create' is available from the location relative to the terminal's current working directory.

## perf
Measure performance aspects of the application.

### Examples
1. `share perf`
   - Starts the performance tool against the default scenario, socket, which measures socket message speed.
1. `share perf 300000`
   - A numeric argument specifies the quantity of events to execute.
1. `share perf insecure`
   - By default the perf command assumes secure protocols (HTTPS and WSS) but supplying the 'insecure' argument will allow use of insecure protocols (HTTP and WS).
1. `share perf socket`
   - Other argument values are interpreted as the type of performance test to run.  Currently the only supported performance test type is 'socket'.

## remove
Remove a file or directory tree from the local file system.

### Examples
1. `share remove path/to/resource`
   - Removes the specified resource.
1. `share remove "C:\Program Files"`
   - Quote the path if it contains non-alphanumeric characters.

## service
Launches a localhost HTTP service and web sockets so that the web tool is automatically refreshed once code changes in the local file system.

### Examples
1. `share service`
   - Launches the service on default port 443 and web sockets on port 444.
1. `share service 8080`
   - If a numeric argument is supplied the web service starts on the port specified and web sockets on the following port.
1. `share service 0`
   - To receive a random available port specify port number 0.
1. `share service browser`
   - The 'browser' argument launches the default location in the user's default web browser.
1. `share service test`
   - The 'test' argument tells the service to use data from a separate settings location for running tests instead of the user's actual data.
1. `share service test browser 9000`
   - An example with multiple supported arguments.  The supported arguments may occur in any order.
1. `share service ip:192.168.1.125`
   - An argument that begins with 'ip:' forces use of the specified IP address.  Any string passed as an address will be attempted as a service hostname, but will error if not a locally available IP address.
1. `share service insecure`
   - The 'insecure' argument forces the service to use insecure protocols: HTTP and WS, as opposed secure alternatives: HTTPS and WSS.  Insecure mode is available for local testing but will not allow communication to remote agents.
1. `share service firewall`
   - The firewall argument updates the firewall settings specific to this application.  Currently the firewall utility only supports Windows Defender Firewall.

## test
Builds the application and then runs all the test commands

### Examples
1. `share test`
   - Runs all the tests in the test suite.

## test_browser
Launches the 'service' command as a child process, launches the default browser to execute DOM instructions as intervals of test automation, and then closes the browser upon completion.

### Examples
1. `share test_browser`
   - Runs the browser interaction tests. If not test suite is specified by name all test lists will be executed. Every test list, aside from 'self' requires 4 other computers executing in mode 'remote'.
1. `share test_browser no_close`
   - Disables the 'window.close()' command at the end of test instructions so that the browser remains open for manual inspection.
1. `share test_browser demo`
   - Same as the 'no_close' argument but also imposes a half second delay between actions so that a person can watch the interactions.
1. `share test_browser self`
   - The argument 'self' executes tests from the ./lib/terminal/test/samples/browser_self.ts test list. These tests only execute on this local device and do not make use of other computers.
1. `share test_browser delete`
   - The argument 'delete' executes tests from the ./lib/terminal/test/samples/browser_delete.ts test list. This mode requires 4 other computers executing in mode 'remote'.
1. `share test_browser device`
   - The argument 'device' executes tests from the ./lib/terminal/test/samples/browser_device.ts test list. This mode requires 4 other computers executing in mode 'remote'.
1. `share test_browser user`
   - The argument 'user' executes tests from the ./lib/terminal/test/samples/browser_user.ts test list. This mode requires 4 other computers executing in mode 'remote'.
1. `share test_browser remote`
   - The argument 'remote' puts a computer into listening mode awaiting instructions from a computer executing agent type tests. Computers in this mode will not exit the service automatically.
1. `share test_browser "C:\Program Files\Mozilla Firefox\firefox.exe" no_close`
   - By default tests only execute against the default browser.  To test against other locally installed browsers simply provide the absolute path to the browser binary.

## test_service
Launches the 'service' command as a child process to issue HTTP requests against it and test the results

### Examples
1. `share test_service`
   - Runs tests service utility.
1. `share test_service fs-copy`
   - Filter the tests to run by supplying a text fragment to filter against test names.  For example if there are 6 service tests whose names contain that string then only those 6 tests will be evaluated.
1. `share test_service "Copy from Remote Device to different Remote Device"`
   - Using quotes the filter argument may contain spaces and other non-alpha characters.

## test_simulation
Launches a test runner to execute the various commands of the services file.

### Examples
1. `share test_simulation`
   - Runs tests against the commands offered by the services file.
1. `share test_simulation help`
   - Filter the tests to run by supplying a text fragment to filter against test names.  For example if there are 6 service tests whose names contain that string then only those 6 tests will be evaluated.
1. `share test_simulation "hash ~/share-file-systems list ignore ['node_modules'"`
   - Using quotes the filter argument may contain spaces and other non-alpha characters.

## typescript
Performs TypeScript type checks without writing compiled output.

### Examples
1. `share type`
   - Executes TypeScript type evaluation.  Equivalent to `npx tsc --pretty`.

## update
Pulls code from the git repository of the current git remote and branch, rebuilds the application, then executes a command. The child command will always execute from the project's absolute directory.

### Examples
1. `share update`
   - If no additional arguments are provided the child command to execute will be: share service
1. `share update test_browser`
   - The child command will be: share test_browser
1. `share update lint ../tools ignore [node_modules, .git, test, units]`
   - All arguments are passed into the child command equivalent to: share lint ../tools ignore [node_modules, .git, test, units]

## version
Prints the current version number and date of prior modification to the console.

### Examples
1. `share version`
   - Prints the current version number and date to the shell.

## websocket
Launches a localhost web socket server.

### Examples
1. `share websocket`
   - Launches a websocket server on a random port.
1. `share websocket 8080`
   - If a numeric argument is supplied the server starts on the port specified.
1. `share websocket 0`
   - To force a random available port specify port number 0.
1. `share websocket ip:192.168.1.125`
   - An argument that begins with 'ip:' forces use of the specified IP address.  Any string passed as an address will be attempted as a service hostname, but will error if not a locally available IP address.
1. `share websocket secure`
   - The 'secure' argument forces the server to use secure protocol WSS.  If both 'secure' and 'insecure' arguments are supplied 'secure' takes precedence.  A secure server requires that a certificate in PEM format with file extension 'crt' be saved in 'lib/certificate' directory under this project along with its corresponding key file.
1. `share websocket insecure`
   - The 'insecure' argument forces the server to use insecure protocol WS.  If both 'secure' and 'insecure' arguments are supplied 'secure' takes precedence.
