VFS Shell Commands

The following commands are available. Note that you can add your own easily.

Boxed commands:

Boxed commands are commands that are used in a boxed shell that confines the user to a specific file system and limits the configurability of the system. They are typically used in a server environment where you would want to avoid the user from accessing the local files or from adding harmful commands.


Asserts whether a file or folder exists. With the -n flag you can assert the inverse: that it does not exist. Use the -f flag if you want to assert it is an existing file; use -d to assert it is a directory. To verify the current working directory you can give option --cwd=path; if the given path does not resolve to the current working directory an error is issued.


  assert myexistingfile.txt
  assert myexistingdir
  assert -n nonexisting
  assert -f myexistingfile.txt
  assert -d subdir/myexistingdir  
  assert . --cwd=file:///etc/tmp
  assert . --cwd=/etc/tmp


File object attribute manipulation. There are three subcommands: info, get and set: info shows all of the attributes of the specified file object; get shows the specified attribute; set changes the specified attribute to the given value.

The availability of attributes depends on the specific filesystem.


 attrs info myfile.txt
 attrs get title myfile.txt 
 attrs set title newtitle myfile.txt 


Runs the Beanshell script specified. If you use the -e flag you can enter the expression directly, otherwise the specified file will be loaded. You can also use the -e flag to run any Java class.

The script has access to all variables set in the engine. When you load a file it will have access to the arguments as "args". When loading a file you can also pass flags using the --flags option; all values will be set as additional flags.

When using quotes in an expression you must be aware that they are first interpreted by the shell as token delimiters; you need to escape them.


 bsh -e print(cwd);
 bsh -e print(cwd + \" hello world\");
 bsh -e 'print(cwd + " hello world");'
 bsh -e org.apache.xalan.Version.main(new String[]{});
 bsh -e 'System.out.println(System.getProperty("java.version"));'
 bsh test.bsh hello world -fva --option1=doit

The file test.bsh could be something like:

 print ("cmd: " + args.cmd + " first arg:" + args.getArgument(0));

See: load, register


Dumps the content of a file to the console.


Change the current working directory.


 cd lib
 cd zip://C:/temp/archive.zip
 cd dctm://dmadmin:pwd@MyDocbase/System
 cd ~1

The last example (cd ~1) is related to the dirs, pushd and popd commands. The number corresponds to the directory stack that is manipulated using pushd and popd. The command dirs shows the current state of the directory stack.

See: dirs,pwd


Closes a filesystem. You can specify which filesystem you want to close, otherwise the current filesystem is closed. With the -a flag you can close all open filesystems at once.


  close zip://C:/temp/archive.zip
  close -a

See: open


Compares two files or folders.

The first argument represents the source, the second the target. What drives the equality of two files can be configured. By default the date is used (you can also use flag 'd'), if the source is newer it will be considered the same; using the 'N' flag you can modify this to a stricter date comparison, only when the date matches exactly will the files be considered equal. If flag 's' is given the size will be used; if there is a difference in size then the target will be overwritten. If flag 'm' is given the md5 codes are calculated and compared; note that this is much slower. When you combine flags then the comparisons are combined; e.g. -sd means that the size and the date are compared; if you give multiple options the evaluation order is date > size > md5.

To have more details about the differences you can trigger the verbose mode with flag 'v'.

If you want to act on the differences you should use the sync command.


 compare sourcefile.txt remotefile.txt -mv
 compare ftp://anonymous@server/httpd local/httpd -sdNv 

See: sync


Copy the file or directory to the specified location. If you specify the -P flag then it will not try to preserve the modification date; by default it will try to keep it. Flag -v will do the copy in verbose mode.

Note that the cp command will always overwrite the files; you can use the sync command if you do not want to copy up-to-date files.


 cp archive.zip file:///C:/temp 
 cp archive.zip file:///C:/temp/renamed_archive.zip
 cp mydir /temp -Pv

See: sync


Shows the directory stack. The items on the stack can be accessed using a number. The current working directory always has number 0. A new item put on the stack will get number 1.

You can access directories on the stack using cd ~n where n is a number of a directory on the stack.

You can manipulate the stack by pushd and popd. Since the directory on top is the current directory the cd command also influences the stack.

Note that the stack can hold only 99 items.


 Directory stack (newest first)
   [0] file:///C:/temp
 vfs>pushd ..
 Current folder is file:///C:/
 Directory stack (newest first)
   [0] file:///C
   [1] file:///C:/temp 

See: peekd, popd, pushd


Prints the arguments to the output. Use it to print variables. You can activate, deactivate and show the current status using flags --on, --off and --status. When you use one of these flags the other arguments will not be echoed.


 echo current dir: $cwd
 echo --status
 echo --on
 echo --off


Prints the last occurred error. If you specify the -p flag the stacktrace related to the error is printed. Giving the --halt flag will print the status of the 'halt on error' behaviour; if you give a value you can change this behaviour. You can clear the current error using the --clear flag. In some testing scenarios you want to force an exception when there is no error, you can use the --assert flag for this. This mainly functions as a delayed error activation mechanism.


 error -p
 error --halt
 error --halt=yes
 error --clear
 error --halt=no
 ... <do something>
 error --halt=yes
 error --assert="my message" 

exit, bye, quit

Exit the shell


Finds files or folders. The difference with ls is that ls will collect all matches before printing, while find is memory efficient because it prints while walking the directory tree.

You can also execute commands on matched files by using the exec option, by default it will print the relative path. In the exec option the following tokens are replaced with the value corresponding to the document: {relpath} for the path relative to the current working directory, {abspath} for the absolute path within the file system and {fullpath} to have the full URI including the file system. If you don't specify any of these then the relative path will be appended to the exec command.

You can steer the behaviour in several ways.

Flag 'f' will force a stop on the first error that is encountered.

Flag 'C' will make the match case insensitive.

Flag 'd' will do a depth first traversal wich means the folders are treated after their children (useful for rm commands). Option 'maxdepth' will stop when the given number of levels are traversed.

When you give long flag 'files' only files are considered, when you give 'folders' only folders are considered.

You can also filter on age, size and custom attributes.

Age will take a pattern of the form <operator><value><unit>, where operator is gt, gte, lt, lte, eq or neq (not equals); unit is ms for milliseconds, s for seconds, m for minutes, h for hours, d for days, w for weeks. If no unit is given days is assumed.

Size will take a pattern of the form <operator><value><unit>, where operator is gt, gte, lt, lte, eq or neq; unit is b for bytes, k for kilobytes, m for megabytes and g for gigabytes. If no unit is given then bytes is assumed.

Custom attributes take the pattern [<name><operator><value>(, <name><operator><value>, ...], where name is the name of the attribute and operator is == or != (or the equivalent ).


 find --files **/*Tmp --age=gt1w --exec=rm
 find --files **/*.pdf -C --size=gte10m --exec="echo {fullpath}" 
 find **/* --attrs="[title=='Hello World', abstract!='The World is abstract']" --maxdepth=2

See: ls


Calculates the hashcode of the given arguments. You can also give a checksum with which the hashcode will be compared with the checksum option.


 hash "calculate this hascode" and "this is the third"
 hash "hello world" --checksum=1794106052


Shows the list of available commands. When you give a command it will show the usage information of the command.


 help mv


Loads a file with shell commands. The commands are executed in the current context. If you don't want to change the current context you can use the -c flag. By default it does not echo the read commands, you can activate echoing using the -e flag.

The script has access to all of the arguments that were specified together with the file. You can use $args to get all arguments or $arg1, $arg2, etc. for individual arguments. You can use $cmd for the name of the script, $flags for the flags and $options for the options. To get around the -c en -e flags being caught while calling the script you can pass the --flags option, all values will be passed as additional flags.


 load incontext.vfs hello --world 
 load -ce newcontext.vfs hello world --flags=cde 

See: bsh, register


Lists the content of a directory. With the -l flag you get the long listing. You can specify a filter to limit the listing. If you specify a directory wildcard (**/) subdirectories are searched too.


 ls -l
 ls **/*.zip

See: find


Calculates the MD5 checksum. It works on files, not on folders. If you give the 's' flag the arguments are taken as a literal string for which the MD5 will be calculated. A 32 character hex value will be printed to the console. You can also give a checksum to compare the calculated MD5 with with the 'checksum' option.

With the 'c' flag you can point to files containing a checksum value and optionally a file name (in format 'checksum filename'). If the file does not contain a filename then the name of the checksum file without '.md5' will be used to find the file for which the MD5 should be calculated.

  md5 myfile.txt --checksum=609b286c68168d58e8424a4f4146211b
  md5 mydir/*.txt 
  md5 -s "what is my checksum" "and mine?"
  md5 -s "what is my checksum" --checksum=609b286c68168d58e8424a4f4146211b
  md5 -c *.md5


Create a directory. If the directory already exists, a message will be printed, but it will not be considered an error - but an existing file with the same a name is considered an error. You can add multiple levels at once.

  mkdir tmp
  mkdir tmp/subdir
  mkdir new/subdir


Move the file or directory to the specified location. You can use this too to rename files and directories.


Opens a filesystem with optional explicit authentication.

When you specify flag u the username will be asked, when you specify flag p the password will be asked, when you specify flag d the domain will be asked. These will supplied as login credentials together with the URI that is opened. Typically you would want to provide the -p flag because VFS is notorious for printing passwords that are specified in the URI.

When you don't specify a URI a list of open filesystems is shown.

You are not obliged to use the open command to open filesystems, you can also use the cd command if you specify all parameters in the URI. The difference with the cd command is that you can access layered filesystems more easily, that you can protect your password and that you can explicitly close opened filesystem.


 open -up dctm://MyDocbase
 open -p ftp://admin@localhost
 open archive.zip

See: close


File object operation support. There are three subcommands: list, do and usage.

'list' lists the available operations on the specified file object.

'do' executes the operation; you can use the name or the sequence number of the operation to address it.

'usage' shows the parameters of the operation; you can use the name or the sequence number of the operation to address it. Note that only options are supported to address the parameters.

The availability of operations depends on the specific filesystem. The parameters are deduced from the bean spec by scanning all the writable properties.

 ops list myfile.txt
 ops usage validate myfile.txt
 ops do 1 myfile.txt 
 ops do validate --optionx=true myfile.txt


Changes the working directory to the last one pushed on the directory stack without removing it from the stack. It is equivalent to cd ~1.



See: dirs, popd, pushd


Remove a folder to the directory stack and change the working directory to it. If you provide the -n flag the current working directory will not change but only the stack will be reduced.


 popd -n

See: dirs, peekd, pushd


Add a folder to the directory stack. When you don't give any arguments it will push the current directory to the directory stack. When you give a path it will also change directory to the given path afterwards. If you provide the -n flag than the provided path will be put on the stack and the current working directory will not change.


 pushd ../../lib
 pushd zip://c:/temp/archive.zip
 pushd -n dctm://dmadmin:pwd@MyDocbase/System

See: dirs, peekd, popd


Registers the given class or scripts as commands, it supports java classes, vfs scripts and beanshell scripts.

This allows for easy extension of the existing commands using command classes in the classpath and using macro-like functions with vfs scripts or more enhanced scripts using beanshell.

For the effect of calling a vfs script see the load command, for the effect of calling a beanshell script see the bsh command.

To register a class you can specify option --type=class; but also if you don't specify any option an attempt will be made to map the given argument to a class. The class should be a subclass of the CommandProvider class.

If you use a script that has extension '.vfs' or '.bsh' the type is detected, but you can also specify it explicitly using the type option. The name of the script, without its extension, is used for registering it.

You can override the name that should be used for the command, and also the description and usage information, but not when you use a wildcard to find multiple scripts. For classes this will only work when your class is a subclass of AbstractCommand.

Note that the registered command will replace an existing command with the same name; be careful with what you do.

Normally the content of the script is read each time it is executed. You can also store the script in memory using the --cache flag; changes in the script will then not be activated until you register the script again.

You typically use register in the .vfsshellrc init script you add your own commands.

Examples :

  register org.vfsutils.shell.commands.Ls --name=dir --type=class
  register org.vfsutils.shell.commands.Cp --name=copy --cache 
  register d:/temp/test.vfs --description="test script" --usage="<path>"
  register d:/temp/test --type=bsh --name=mycommand
  register scripts/*.bsh
  register my-scripts/*.*

See: bsh, load, unregister


Does not do anything. Use this or # to comment lines out.


 rem does nothing
 # does not do anything either


Remove the specified file or folder. It does not remove non-empty directories. You have more verbose output when you specify the -v flag. The -F flag indicates that the command should not fail if the remove does not work. For safety you can not remove everything in a filesystem using 'rm /**/*'; however, if you are in the root and do 'rm **/*' no warning will be issued. The rm command does a depth first transversal using the pattern which means that folders are removed after their children.


 rm myfile.txt
 rm folder/**/* -v
 rm nonexisting*.txt -Fv


Sets environment variables that you can later use by prefixing a $ sign to the name. To unset a variable just give the name.

You always have access to the $cwd and $cwp variables; the first contains the full name of the current working directory, the second the path within the filesystem. Note that changing them has no effect; the next cd command will reset them.

You can change the prompt by setting the PROMPT variable. To add the full name of the current working directory set it to \n, to add the path within the current file system set it to \p.


 set myvar=file://d:/temp
 cd $myvar
 set myvar
 set curdir=$cwd
 set PROMPT="\\n > "
 set PROMPT="\\p#"
 set PROMPT="vfs > "


Measures elapsed time. It has four subcommands: start, lap, total and stop. start resets the timer and starts it lap shows the time since the last lap or since the start if it is the first lap, total shows the time spent since the timer started stop shows the time spent since the timer started and resets it

Using lap or total before a start, or after a stop, will start the timer.


 stopwatch start
 stopwatch lap
 stopwatch lap
 stopwatch total


Synchronizes two files or two directories. The synchronisation is unidirectional. The first argument represents the source, the second the target. What drives the equality of two files can be configured. By default the date is used; if the source is newer it will overwrite the target; this behaviour can also be triggered by flag 'd'. If flag 's' is given the size will be used; if there is a difference in size then the target will be overwritten. If flag 'm' is given the md5 codes are calculated and compared; note that this is much slower. When you combine flags then the comparisons are combined; e.g. -sd means that the size and the date are compared; if you give multiple options the evaluation order is date > size > md5.

If you specify flag '--delete' then superfluous files in the target directory are removed.

Flag '--dry-run' will do a trial run that will not actually copy or delete files.

The copy behaviour can be influenced by flag 'P'; when given it will not try to preserve the modification date (note that setting the modification date might not be supported by the target filesystem); by default it is tried.

The 'v' flag will output each operation performed.

There is no mode to force overwriting all files; you can use the cp command for that.

Note that this implementation is not optimized for very large datasets and is not a replacement for rsync.


 sync sourcefile.txt remotefile.txt -mPv
 sync ftp://anonymous@server/httpd . --delete -sd --dry-run

See: cp, compare


Shows system information such as the memory usage, the number of available processors, thread information and system properties. It can also trigger a garbage collection and a finalization.

By default it will show only a summarized view: the number of threads instead of a list of threads and the java and os versions instead of all system properties. Using flags you can indicate that you want to see the details. Use flag 't' for thread information and flag 'p' for properties. If you use such a flag the other information is not shown, unless their flag is also given. E.g. '-t' will only show thread information while '-tp' will show threads and properties. Use the 'm' flag to also show memory information and the 'a' flag to show all information.

To trigger garbage collection use flag 'gc' and to trigger finalization use flag 'finalize'.


 sysinfo --finalize --gc
 sysinfo -tm
 sysinfo -mp
 sysinfo --gc -a


Resets the modification date of a file (if supported by its filesystem).


Unregisters commands. If flag --all is given then all commands are removed from the registry except register, unregister and help commands. These commands can be removed by explicitly calling a remove on them though. When you unregister the unregister command you can not unregister anymore.

You can also unregister all commands except those explicitly specified using the --keep flag. Note that this will still keep register, unregister and help even though you didn't specify them.

 unregister sysinfo hash
 unregister cd ls md5 --keep
 unregister --all
 unregister register help unregister

See: register

Operations on XML files, such as cat and copy that support XPath. The flags u and e are used to unencode or encode XML (escaping the main control characters). With the P flag you will see the raw XML, not pretty printed.

The xpath option allows you to specify a xpath v1.0 path in the document; because xpath 1.0 does not allow nodes that have a default namespace to be referenced without a namespace you have to use namespace prefix ns: in those cases. Note that xpaths in namespace-complicated documents might not work correctly in this implementation. You can use flag f to select only the first matching node. Because of the quote handling on the command line you'll have to escape quotes in your xpath expressions.


xml cat pom.xml --xpath=/ns:project/ns:dependencies/ns:dependency -f
xml cat pom.xml --xpath="/ns:project/ns:dependencies/ns:dependency[ns:artifactId/text()='junit']"
xml copy pom.xml ram://tmp.txt --xpath=/ns:project/ns:dependencies/ns:dependency -fe


Performs an XSL transformation. It supports different modes: sax, dom and stream which influences the way the source xml and xsl files are read (the default mode is sax). Except for the stream mode a VFS enabled entity resolver is used by the XML parser. The URI resolver used by the transformation is also VFS enabled. VFS enabled means that you can use full VFS URIs in your XSL to access other filesystems.

If you don't specify an output file the result is written to the console.

You can cache the compiled XSL file using the -c flag.

All options that are given are forwarded to the XSL as parameters.

Examples :

 xslt in.xml transform.xsl
 xslt in.xml transform.xsl result.html --param1=a --param2=b
 xslt file://d:/in.xml smb://host/folder/transform.xsl ram://data/result.xml -c

Boxed commands

Boxed commands are commands with limited functionality to avoid escaping the current filesystem or altering the shell.


Opens layered file systems but not external ones.

See: open


Allows registering VFS scripts, but not Beanshell scripts or Java classes. Does not allow replacing a Beanshell script or Java class by a VFS script.

See: register


Allows unregistering VFS scripts, but not Beanshell scripts or Java classes.

See: unregister


Does not allow references to external filesystems in the entities and uris in the XML and XSL files

See: xslt