CPANPLUS::Shell::Default - Default command-line interface for CPAN++


CPANPLUS::Shell::Default - Default command-line interface for CPAN++


To begin use one of these two commands. This will start your default shell, which, unless you modified it in your configuration, will be CPANPLUS::Shell::Default.

    perl -MCPANPLUS -e 'shell'

Shell commands:

    CPAN Terminal> h
    CPAN Terminal> s verbose 1
    CPAN Terminal> e /home/kudra/perllib
    CPAN Terminal> m simple tcp poe
    CPAN Terminal> i 22..27 /A/AL/ALIZTA/Crypt-Enigma-0.01.tar.gz 6 DBI-1.20
    CPAN Terminal> u Acme::POE::Knee 21
    CPAN Terminal> a damian
    CPAN Terminal> t Mail::Box
    CPAN Terminal> c DBI
    CPAN Terminal> r POE
    CPAN Terminal> d --force=1 --no-verbose XML::Twig
    CPAN Terminal> l DBD::Unify
    CPAN Terminal> f VROO?MANS$ DCROSS
    CPAN Terminal> ! die 'Kenny';
    CPAN Terminal> p --all /tmp/cpanplus/errors
    CPAN Terminal> w
    CPAN Terminal> z HTML::Template
    % gremlin[1009] /root/.cpanplus/build/5.6.1/HTML-Template-2.6> exit
    CPAN Terminal> o
    CPAN Terminal> i *
    CPAN Terminal> x
    CPAN Terminal> b
    CPAN Terminal> q


CPANPLUS::Default::Shell is the default interactive shell for CPAN++. If command-line interaction isn't desired, use CPANPLUS::Backend instead.

You can also use CPANPLUS::Backend to create your own shell if this one doesn't suit your tastes.


The shell will accept any combination of options before arguments. Options are prefaced with --. Note that not all options may be appropriate for all commands. Options affect just the command being issued.

The options available are the same as the options which can be specified to the underlying Backend methods. Refer to the Backend method of the same name as the command for a listing of the options available in the CPANPLUS::Backend manpage. For example, to find what options i (install) accepts, look at the documentation for the install method in Backend.

Options may be specified as just the option name, or as =1 to turn on the option, and prefaced with no- or followed by =0 to set them off. In short, these two commands are equivalent--they both turn on force:


To turn off force, either of the following would work:


Naturally this syntax only applies to boolean options. For other options, the following might be more appropriate:



Tab completion is available for the following commands: i t u d l r c and s. For all commands other than s it will expand modules, and for s it expands config arguments.



Help lists available commands and is also the default output if no valid command was given.


Quit exits the interactive shell.


This command performs a case-insensitive match for a module or modules. Either a string or a tailored regular expression can be used. For example:

The list of matching modules will be printed in four columns. For example:

    1 Acme::Pony                1.1   DCANTRELL
    2 Acme::DWIM                1.05  DCONWAY

These columns correspond to the assigned number, module name, version number and CPAN author identification. Assigned numbers can be used for a subsequent commands, either singly (2) or inclusively (1..2). Numbers are reassigned for each search.

If no module version is listed, the third field will be undef.


The author command performs a case-insensitive search for an author or authors. A string or a regular expression may be specified; both CPAN author identifications and full names will be searched. For example:

This command gives the same output format as the module command. Sometimes the output may not be what you expected. For instance, if you searched for jos, the following listing would be included:

    1 Acme::POE::Knee           1.02  KANE

This is because while the CPAN author identification doesn't contain the string, it is found in the module author's full name (in this case, Jos Boumans). There is currently no command to display the author's full name.


This command installs a module by its case-sensitive name, by the path and filename on CPAN, or by the number returned from a previous search. Distribution names need only to be complete enough for distinction. That is to say, DBI-1.20 is sufficient; the author can be deduced from the named portion.


Install will search, fetch, extract and make the module.


This command is exactly the same as the i above, only it will not actually install modules, but will stop after the make test step. Unlike the i command, it performs on modules that are already installed, even if the force flag is set to false.


This command will uninstall the specified modules (both program files and documentation). Modules can be specified by their case-sensitive names, or by the numbered result from the last search.


This command fetches test results from the CPAN tester's website at and displays the results for the most recent version of a module, specified by its case-insensitive name, or by the number of a previous search.

If passed the path and filename of the module, it will display the test results for the version specified.


The read command displays the readme for the specified module or distribution. It accepts the case-sensitive name of the module or a number from a previous result, and can accept multiple arguments.


This command will download the module or modules in the current directory. It is case sensitive. Like install, it can also accept a fully qualified file name from a CPAN mirror, relative to the /authors/id directory. All file names should begin with a /.


This command adds directories to your @INC. CPAN++ will check to see if modules are already installed on your system, so if there is a custom library directory it should be specified. Examples:


This command lists detailed information about a module or distribution.

Example output from the list command:

    Details for Net::FTP:
    Description          Interface to File Transfer Protocol
    Development Stage    Alpha testing
    Interface Style      plain Functions, no references used
    Language Used        Perl-only, no compiler needed
    Package              libnet-1.09.tar.gz
    Support Level        Developer
    Version              2.61


This command gives a listing of distribution files by the author or authors specified. It accepts a case-insensitive regular expression.

Output from the previous command would look like this:

    1    12230 KANE
    2    14246 KANE
    3    12324 KANE
    4     6625 KANE
    5 CPANPLUS-0.01.tar.gz     120689 KANE
    6 CPANPLUS-0.02.tar.gz     121967 KANE

The first column is the search result number, which can be used for subsequent commands. Next is name of the distribution, the third column is the file's size, and the fourth is the CPAN author id.

s [conf | save | OPTION VALUE]

The set command can be used to change configuration settings. If there are no arguments, current settings are displayed.

s conf will let the user go through the configuration process again, and save the settings to the CPANPLUS::Config manpage.

s save will save the current settings for this session.

The OPTION VALUE form will override current settings for this session; they will be cleared away when the Shell exits. Available options are:

p [--option] [FILE]

This allows the printing of stored errors, either to standard out or the specified file.

An option may be supplied if desired. Available options are --all, --msg and --error. If no option is supplied, --error will be assumed. The --all flag prints both errors and messages, while the --msg flag prints just messages.

It is useful to include --all output when reporting a bug.

o [--long] [MODULE]

This command lists installed modules which are out-of-date.

Example output:

    1   0.05     0.06   Acme::ComeFrom         AUTRIJUS
    2   1.01     1.07   Acme::EyeDrops         ASAVIGE
    3   1.00     1.01   Acme::USIG             RCLAMP
    4   2.04     2.1011 DBD::mysql             JWIED
    5   1.13     1.15   File::MMagic           KNOK

The first column is the search result number, which can be used for subsequent commands. Next is the version you have installed, followed by the latest version of the module on CPAN. Finally the name of the module and the author's CPAN identification are given.

You can provide a module name to only check if that module is still up to date. By default, only one module per package is printed as being out of date. If you provide the --long option however, all modules will be printed.


The 'what' command will print the results from the last match. This is useful if they have scrolled off your buffer.


This command refetches and reloads index files regardless of whether your current indices are up-to-date or not.


This command will autobundle your current installation and write it to $cpanhome/$version/dist/autobundle/

For example, the bundle might be written as:



The z command will open a command prompt in the distribution directory. If the module hasn't been downloaded and extracted yet, this will be done first. Exiting the command prompt will return you to the CPANPLUS shell. If multiple modules are entered, a new command prompt will be given for each module.


This command evals all input after it as perl code, and puts any errors in the error stack.


This module by Jos Boumans <> and Joshua Boschert <>.

This pod text by Ann Barcomb <>.


The CPAN++ interface (of which this module is a part of) is copyright (c) 2001, 2002 Jos Boumans <>. All rights reserved.

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.


Andreas Koenig <> authored the original module.


the CPANPLUS::Backend manpage, the CPANPLUS manpage,

 CPANPLUS::Shell::Default - Default command-line interface for CPAN++