admin_tool1Add my vote for this tag automation1Add my vote for this tag dev_essential1Add my vote for this tag development1Add my vote for this tag shell1Add my vote for this tag web_services1Add my vote for this tag create new tag
, view all tags

TWiki Shell


TWikiShellContrib is a shell that can be use to replace all twiki command line scripts with a single interface. Each command available in the twikishell is also available as a command line option (i.e: to invoke the help command, type twikishell help)


In the TWiki home directory, there is an uber-command:

  • twikishell

This will fire the shell. The following command line options are available:

Option Description
-v Verbose mode (Verbosity level 1) (Default)
-vv Very Verbose mode (Verbosity level 2)
-q Quiet Operation (Verbosity level 0)
-d Turns on debugging (prints debug statements to console)
<command> Execute the specified command. Must be the last option in the cli. i.e: twikishell package CalendarPlugin


When the shell starts, it first try to load the .twikirc file for the stored configuration. If it can't find it, it will create an empty configuration, and is up to each CommandSet to reconfigure themselves.

On a bare installation (without any CommandSets installed), you have the following available commands:

Command Description
help Shows a list of available commands
help <command> Shows a detailed help of the specified command
help <command> <subcommand> Shows a detailed help of the specified subcommand
exit, q, quit Quits the shell
import <perl module> Imports a perl module and scan it for new commands to be added to the shell
verbose <level> Changes the verbosity level to either 1 or 2
quiet Changes the verbosity level to 0
debug Set debugging On and Off. Usage: debug [on/off]

The config file is a dump (using CPAN:Data::Dumper) of the configuration object used internally


CommandSets are the extension point for TWikiShellContrib. Without them, it's only an empty shell (no pun intended)


CommandSets are perl modules that defines one or more of the following subs:

Sub Description
run Command execution
smry One-line help to be used by "help" to sumarize all the commands
help Complete help to be shown by the "help <command>" command
run_<subcommand> SubCommand execution
smry_<subcommand> One-line help to be used by "help" to sumarize all the commands
help_<subcommand> Complete help to be shown by the "help <command> <subcommand>" command

There are several ways to implement CommandSet. The first thing to understand is how the commands map to perl modules and handler subs. See the following table:

command/subcommand Module Name Implemented Handlers
dump Dump run, smry, help
dump config Dump run_config, smry_config, help_config
Dump::Config run, smry, help
dump handlers Dump run_handlers, smry_handlers, help_handlers
Dump::Handlers run, smry, help

The CommandSet can be on any TWiki subpackage and can be imported using the import command. The special case are CommandSet under the TWiki::Contrib::CommandSet package (anywhere in @INC) which are "discovered" and imported at startup.

Check the bundled CommandSets for examples on how to implement them.

Initializing CommandSet

Any CommandSet that needs an special initializacion when imported can use the following hook:


Called when the CommandSet is being imported.

Loading a CommandSet to the Shell

To load a CommandSet, use:

   import <command>


   import <CommandSet_module_without_prefix>

if it's a core CommandSet, or

   import <CommandSet_module>

if not.

Also, if the CommandSet is in the package TWiki::Contrib::CommandSet it will be imported automatically on it first invocation (for example, the Dump CommandSet will be loaded automatically when the dump, dump config or dump handlers commands are called).

CommandSet contract

All the handlers (run, help and smry) will be called with the following parameters (in order):

Parameter Description
$shell A reference to the shell object
$config A reference to the config object
@args The list of parameters passed to the command

Warning: Can't find topic Plugins.TWikiShellBundledCommandSets

Warning: Can't find topic Plugins.TWikiShellConfigObject

Warning: Can't find topic Plugins.TWikiShellServices


  • Make sure that CPAN:Term::Shell is installed (either in the perl distribution or locally in twiki)
  • Unzip TWikiShellContrib.zip in your twiki installation directory. Content:
    File: Description:

If you have a non-standard instalation, then move the files wherever you need them to be.


  • Short description
    • Set SHORTDESCRIPTION = TWiki shell to access TWiki from the command line

  • Name of the perl package
    • Set STUB = TWiki::Contrib::TWikiShellContrib

Contrib Info

Authors: TWiki:Main.MartinCleaver, TWiki:Main.RafaelAlvarez
Copyright ©: 2004,2005 Crawford Currie, Rafael Alvarez, and Martin Cleaver
License: GPL
Dependencies: CPAN:Term::Shell
10/08/2005 2.0 Removed reload and register commands. Major overhaul of the code. Added new CommandSets
02/11/04 1.1 Added reload and register commands
21/10/04 1.000 Initial release, based on the work of TWiki:Main.MartinCleaver
Home: http://TWiki.org/cgi-bin/view/Plugins/TWikiShellContrib
Feedback: http://TWiki.org/cgi-bin/view/Plugins/TWikiShellContribDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/TWikiShellContribAppraisal

Related Topics: TWiki:Codev.TWikiShell

Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatmd5 TWikiShellContrib.md5 r1 manage 0.2 K 2006-05-19 - 03:13 MartinCleaver md5 checksums
Compressed Zip archivetgz TWikiShellContrib.tgz r1 manage 33.5 K 2006-05-19 - 03:13 MartinCleaver Untar and run the installer script, if there is one
Compressed Zip archivezip TWikiShellContrib.zip r2 r1 manage 48.1 K 2006-05-19 - 03:13 MartinCleaver unzip, correct the permissions, and run the installer script, if there is one
Edit | Attach | Watch | Print version | History: r10 < r9 < r8 < r7 < r6 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r10 - 2006-05-20 - PeterThoeny
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.