VFS Shell

This project provides a Java Shell interface (or Java Command Line Interface) using VFS.

The shell interface is inspired on the Shell example that comes with the Apache Commons VFS library but it is more extensible and adds more functionality.

Its first intent is being a file system manipulation shell, not a Java application launcher.

It is easy to add commands or to change the behaviour of the existing commands. From within the shell you have access to the engine to set variables and dynamically add new commands and use scripts.

You can setup the environment using scripts that are loaded when the shell starts, see Configuration.

You can use JLine with the VFS JLine Shell integration. It adds tab completion for commands and file names and does password masking on the open command. This makes the Shell a whole lot more professional. In the binary distribution JLine is enabled by default.

Using the Apache Mina SSHD Server as core you can setup a secure server shell application with the VFS SSHD Server integration. Users can connect with a normal ssh client and perform shell operations on your remote virtual filesystem. By default the shell only offers limited operations to avoid users from 'escaping' from the preconfigured file system. Of course you can easily change or add commands to make your own shell environment. The SSHD server supports SCP and SFTP for file transfer.


You can download the binary distribution or the individual libraries at the SourceForge download page.


The available commands are:

  • open: opens a filesystem and asks for username / password
  • close: closes a filesystem
  • cd, pushd, popd, peekd, dirs: directory manipulation
  • ls: directory content listing
  • find: find files or folders and optionally execute a command on them
  • cp, mv, mkdir, rmdir, rm: basic file manipulations
  • compare: compare two file or directories
  • sync: synchronize two directories
  • attrs: meta data (attribute) manipulation (get, set, info)
  • ops: vfs operation interaction (list, do, usage)
  • cat: dumps the content of a file
  • touch: resets the modification date
  • error: details of last occurred error
  • set: sets variables
  • load: executes a file containing shell instructions
  • bsh: executes a beanshell script file or expression
  • register, unregister: (un)registers a new class or script as a command
  • md5: calculates and compares md5 checksums
  • hash: calculates Java hash codes
  • xslt: does an XSL transformation
  • rem: does nothing
  • echo: writes output
  • assert: verifies a file exists
  • sysinfo: shows information about threads, memory and system properties
  • stopwatch: track execution time
  • help: displays the list of commands

To exit the shell you can use exit, quit or bye.

See the list of available commands for more details.

Clearly this list can be extended with all kind of other commands.

Argument parsing

The arguments passing is somewhat standardized. Normal arguments are given separated by whitespace.

Flags exist in two flavours, short flags and long flags. Short flags have one character and can be combined in a single argument: -ef passes the flags e and f. Long flags are multi-character flags, e.g. --delete. They should be used when the flag has a big impact or when there are no short flags left.

Options are key value pairs; e.g. --format=json. The pattern '-format json' is not supported; it will be interpreted as a bunch of flags and one argument.

The order of the arguments is only important for normal arguments; 'sync fromdir todir -sd --delete --dry-run' is equal to 'sync -d --dry-run fromdir --delete todir -s'.

Whitespace can be escaped using a backslash, e.g. cd Program\ Files, but also using single or double quotes: 'Program Files' or "Program Files". If you're lazy you can also skip the closing quote, e.g. cd "Program Files.

Multi-line input is possible when you end the line with a single backslash ('\').

The variables in the input are resolved before tokenizing and interpretation of the line, which means you can also create a variable for a command and create macro-like structures, e.g. set x="cd /tmp".

Currently you can not chain commands, nor pipe them or do things in the background.


There is no bash-like control flow logic, but there are two types of scripts possible: beanshell scripts and vfs scripts, both have arguments passed to them. The scripts can also be registerd as normal commands (see the register command).

The vfs scripts are plain sequences of shell commands, see the load command.

The beanshell scripts have access to all variables and to the shell-engine, see the bsh command.


 cd '/Program Files
 pushd file:///c:/temp
 open vfsshell-dev.zip
 cp vfsshell-dev file://C:/Program\ Files
 attrs info vfsshell.dev
 cd vfsshell-dev
 open -p dctm://dmadmin@MyDocbase/System
 ops do dump Sysadmin
 attrs get r_object_id Sysadmin
 set myvar=file:///c:/temp
 echo $myvar
 set curdir=$cwd
 bsh -e print(myvar);
 bsh myscript.bsh
 cd $myvar

 load myscript.vfs


  • Correct usage of wildcards; currently only relative downward search is supported, you can not go up or provide absolute paths
  • Support for wildcards in mv and some other commands
  • Piping of output to files, chaining commands
  • Starting commands in the background
  • A java command to run any Java application (Though you can already do this using the 'bsh -e' command)
  • Dynamic classpath extension (so you can load a jar from any VFS provider)
  • Additional commands: grep, tail, ...
  • Support for file system options
  • Starting and managing other processes: ps, kill, ...
  • Some default scripts: Purge empty folders, ...
  • Scoping of commands to VFS provider schemes
  • A solution for man pages
  • Better support for documentation of options and flags
  • JLine autocompletion of variables (starting with $)

Other Shells

I didn't go very, very far in studying different Shell/CLI implementations. There don't seem to be that many general purpose Java shells available. The VFS Shell is primarily based on the VFS Shell Example and the Beanshell CLI.

The following projects are of particular interest:

  • Beanshell: More than just a CLI, it provides the interactive interface to the Beanshell Interpreter
  • VFS Shell example: Part of VFS, very basic shell to demonstrate VFS capabilities
  • Felix shell: Part of Felix, Apache OSGi
  • Sshd: Apache Mina SSH Server, a remote Shell
  • GShell: Part of Apache Geronimo