NAME cpanapi

SYNOPSIS

    cpanapi --debug 4 --show-author --id jdeguest --id oalders

DESCRIPTION

cpanapi is a simple command line client to the MetaCPAN API.

COMMANDS

activity

Display as a text chart on the terminal, the aggregate value of releases for the past 24 months.

Default aggregation is 1 month (1M).

For example:

    cpanapi --activity --author oalders

which will show the releases issued by author OALDERS

    cpanapi --activity --author oalders --new

Same as the previous one, but will only show the new distribution release

    cpanapi --activity --distribution HTTP-Message

which will show the releases for the distribution specified.

    cpanapi --activity --module HTTP::Message

which will show the releases that depend on the module specified.

    cpanapi --activity --module HTTP::Message --new

Same as the previous one, but only show new module release.

    cpanapi --activity --new --interval 1M

which will show the new distribution releases across all authors.

autocomplete

This will trigger an API query to the endpoint /search/autocomplete and will return a list of files.

For example:

    cpanapi --autocomplete --query HTTP

changes

This will trigger an API query to the endpoint /changes and will return a list of changes objects, or a change object.

For example:

    cpanapi --changes --distribution HTTP-Message

which will retrieve the changes file information for the specified distribution

    cpanapi --changes --author oalders --release HTTP-Message-6.36

or, you can also specify the author and the release by separating them with a forward slash:

    cpanapi --changes --release oalders/HTTP-Message-6.36

And you can specify more than one author and release combo:

    cpanapi --changes --author oalders --release HTTP-Message-6.36 --author jdeguest --release Nice-Try-v1.3.4

or, separating them with a forward slash:

    cpanapi --changes --release oalders/HTTP-Message-6.36 --release jdeguest/Nice-Try-v1.3.4

Note that the author name is case insensitive.

Possible options to use are:

max

Integer. This specifies the maximum number of lines, starting from the top, in the Changes file to show. Defaults to 7.

For example:
```
    cpanapi --changes --author oalders --release HTTP-Message-6.36 --max 12
```

contributor

This will trigger an API query to the endpoint /contributor and will return a list of contributors and their contributed releases.

For example:

    cpanapi --contributor --author oalders

which will retrieve a list of module contributed to by the specified author.

    cpanapi --contributor --author oalders --release HTTP-Message-6.36

which will retrieve a list of release contributors details.

Possible options to use are:

size

Integer. This specifies the number of elements displayed per page. It defaults to 10.

cover

This will trigger an API query to the endpoint /cover and retrieve the release distribution name, release name, download_url and version number.

For example:

    cpanapi --cover --release HTTP-Message-6.36

diff

This will trigger an API query to the endpoint /diff and retrieve the diff between 2 files ID, or between specific release, or between the last and previous release version of a specified distribution

For example:

    cpanapi --diff --file-id AcREzFgg3ExIrFTURa0QJfn8nto --file-id Ies7Ysw0GjCxUU6Wj_WzI9s8ysU

which will retrieve a diff between 2 files ID.

    cpanapi --diff --author oalders --release HTTP-Message-6.35 --release HTTP-Message-6.36

which will retrieve a diff between the 2 specified releases of the author OALDERS. The author ID is case insensitive.

    cpanapi --diff --distribution HTTP-Message

which will retrieve a diff between the latest and previous version of the distribution HTTP-Message

Note that you can use the option as-text to get the result as text/plain. By default, it will retrieve the data as JSON.

Possible options to use are:

as-text

Boolean. When enabled, this will retrieve the diff as plain text.

download-url

This will trigger an API query to the endpoint /download_url and retrieve the download URL details.

For example:

    cpanapi --download-url --module HTTP::Message --version ">6.35"

which will retrieve the latest download URL details for HTTP::Message with version greater than 6.35

or, using a range of versions:

    cpanapi --download-url --module HTTP::Message --version ">6.30, <=6.36"

which will retrieve the latest download URL details for HTTP::Message with version greater than 6.30, but lower or equal to 6.36

favorite

This will trigger an API query to the endpoint /favorite and retrieve the distributions favorite counts.

For example:

    cpanapi --favorite --agg HTTP-Message --agg DBI

which will retrieve favorites agregate by distributions.

    cpanapi --favorite --distribution HTTP-Message

which will retrieve the list of users who favorited a distribution.

    cpanapi --favorite --user q_15sjOkRminDY93g9DuZQ

which will retrieve user favorites information details.

    cpanapi --favorite --leaderboard

which will retrieve the top favorited distributions (leaderboard) as chart in terminal.

    cpanapi --favorite --recent

which will retrieve a list of recent favorited distributions.

first

This will trigger an API query to the endpoint /search/first and retrieve the abridged module information for the first search result.

For example:

    cpanapi --first --query HTTP

history

This will trigger an API query to the endpoint /history and retrieve the history of the specified module.

For example:

    cpanapi --history --module HTTP::Message --path lib/HTTP/Message.pm

This will retrieve the history of the specified module.

    cpanapi --history --module HTTP::Message --path lib/HTTP/Message.pm --type doc

or, if you prefer to use the full word documentation :)

    cpanapi --history --module HTTP::Message --path lib/HTTP/Message.pm --type documentation

Those previous two will retrieve the history of the specified module documentation.

    cpanapi --history --distribution HTTP-Message --path lib/HTTP/Message.pm

This will retrieve the history of the specified distribution file.

The value for type can be any one of doc, documentation, file, or module

permission

This will trigger an API query to the endpoint /permission and retrieve the owner and co-maintainers information of the specified module.

For example:

    cpanapi --permission --author oalders

This will retrieve the list of all modules where the specified author is either the owner or the co-maintainer.

Note that the author is case insensitive.

    cpanapi --permission --module HTTP::Message

This will retrieve the owner and co-maintainers information for the specified module.

or, for multiple modules

    cpanapi --permission --module HTTP::Message --module Data::HexDump

This will retrieve the list of the specified modules owner and co-maintainers.

pod

This will trigger an API query to the endpoint /pod and retrieve the POD, by default, as HTML string of the specified author, release, path, or of the specified module

Instead of a HTML, you can request the returned data as markdown by using the option --as-markdown, text by using --as-text, POD by using --as-pod. To explicitly request HTML, use --as-html

For example:

    cpanapi --pod --author oalders --release HTTP-Message-6.36 --path lib/HTTP/Message.pm

which will return the module POD, as HTML

    cpanapi --pod --author oalders --release HTTP-Message-6.36 --path lib/HTTP/Message.pm --as-markdown

which will return the module POD converted to markdown.

    cpanapi --pod --author oalders --release HTTP-Message-6.36 --path lib/HTTP/Message.pm --as-text

which will return the module POD converted to plain text.

    cpanapi --pod --author oalders --release HTTP-Message-6.36 --path lib/HTTP/Message.pm --as-pod

which will return the module POD as POD.

    cpanapi --pod --author oalders --release HTTP-Message-6.36 --path lib/HTTP/Message.pm --as-html

which will return the module POD as HTML, which is the default behaviour of the MetaCPAN API.

Alternatively, you can specify a module, such as:

    cpanapi --pod --module HTTP::Message

which will return the module POD for HTTP::Message, or as markdown:

    cpanapi --pod --module HTTP::Message --as-markdown

To get POD data rendered into HTML:

    cpanapi --pod --render $'=encoding utf-8\n\n=head1 Hello World\n\nSomething here\n\n=cut\n'

Note that in command line, passing characters like \n will not turn them into a new line, bu as literals unless you surround your text properly to interpolate them.

reverse

This will trigger an API query to the endpoint /reverse_dependencies and retrieve the list of detailed releases that depend on the specified distribution or module

For example:

    cpanapi --reverse --distribution HTTP-Message --size 10 --page 1 --sort name

which, will retrieve the list of all releases depending on the specified distribution with 10 results per page starting from page 1 and sorting the result by release name.

    cpanapi --reverse --module HTTP::Message --size 10 --page 1 --sort name

Sames as the previous one, except this uses the specified module

search-author

This triggers a search for authors.

For a simple search:

    cpanapi --search-author --query "OA*"

Using a regular expression:

    cpanapi --search-author --regexp "OA.*"

The later will trigger an ElasticSearch using the HTTP POST method.

You can also use an ElasticSearch query stored in a file:

    cpanapi --search-author --es /some/where.json

or using ElasticSearch JSON query passed from STDIN:

    cpanapi --search-author --stdin <<EOT
    {
       "query" : {
          "regexp" : {
             "pauseid" : "OA.*"
          }
       }
    }
    EOT

search-distribution

This triggers a search for distributions.

For a simple search:

    cpanapi --search-distribution --query "HTTP*"

Using a regular expression:

    cpanapi --search-distribution --regexp "HTTP.*"

The later will trigger an ElasticSearch using the HTTP POST method.

You can also use an ElasticSearch query stored in a file:

    cpanapi --search-distribution --es /some/where.json

or using ElasticSearch JSON query passed from STDIN:

    cpanapi --search-distribution --stdin <<EOT
    {
       "query" : {
          "regexp" : {
             "name" : "HTTP.*"
          }
       }
    }
    EOT

search-file

This triggers a search for files.

For a simple search:

    cpanapi --search-file --query "HTTP*"

Using a regular expression:

    cpanapi --search-file --regexp "HTTP.*"

The later will trigger an ElasticSearch using the HTTP POST method.

You can also use an ElasticSearch query stored in a file:

    cpanapi --search-file --es /some/where.json

or using ElasticSearch JSON query passed from STDIN:

    cpanapi --search-file --stdin <<EOT
    {
       "query" : {
          "regexp" : {
             "documentation" : "HTTP.*"
             "name" : "HTTP.*"
             "path" : "HTTP.*"
          }
       }
    }
    EOT

search-package

This triggers a search for packages.

For a simple search:

    cpanapi --search-package --query "HTTP*"

Using a regular expression:

    cpanapi --search-package --regexp "HTTP.*"

The later will trigger an ElasticSearch using the HTTP POST method.

You can also use an ElasticSearch query stored in a file:

    cpanapi --search-package --es /some/where.json

or using ElasticSearch JSON query passed from STDIN:

    cpanapi --search-package --stdin <<EOT
    {
       "query" : {
          "regexp" : {
             "author" : "HTTP.*"
             "distribution" : "HTTP.*"
             "file" : "HTTP.*"
             "module_name" : "HTTP.*"
             "version" : "HTTP.*"
          }
       }
    }
    EOT

search-permission

This triggers a search for permissions.

For a simple search:

    cpanapi --search-permission --query "HTTP*"

Using a regular expression:

    cpanapi --search-permission --regexp "HTTP.*"

The later will trigger an ElasticSearch using the HTTP POST method.

You can also use an ElasticSearch query stored in a file:

    cpanapi --search-permission --es /some/where.json

or using ElasticSearch JSON query passed from STDIN:

    cpanapi --search-permission --stdin <<EOT
    {
       "query" : {
          "regexp" : {
             "owner" : "OA.*"
             "module_name" : "HTTP.*"
          }
       }
    }
    EOT

show-author

Show the information details for one or more author, a.k.a Pause account ID.

For example:

    cpanapi --show-author --id oalders --id jdeguest

Note that the author name is case insensitive.

show-distribution

Show the information details for the specified distribution

For example:

    cpanapi --show-distribution --distribution HTTP-Message

show-file

Show the information details for the specified file or directory path in a given release.

For example:

    cpanapi --show-file --author oalders --release HTTP-Message-6.36 --dir lib/HTTP

which will retrieve a list of all files within that specified release directory.

    cpanapi --show-file --author oalders --release HTTP-Message-6.36 --path lib/HTTP

which will retrieve the specified file information details.

Note that the author ID is case insensitive.

show-package

Show the package information details for the specified distribution or module.

For example:

    cpanapi --show-package --distribution HTTP-Message

which, will retrieve a list of all packages matching the distribution specified.

    cpanapi --show-package --module HTTP::Message

which, will retrieve a list of all packages matching the module specified.

show-release

This will trigger an API query to the endpoint /release, and retrieve the release information.

    cpanapi --show-release --all oalders

which, will retrieve a list of all releases for a given author

    cpanapi --show-release --author oalders

which, will retrieve a shorter list of all releases for a given author

    cpanapi --show-release --author oalders --latest

which, will retrieve the latest releases by the specified author

    cpanapi --show-release --author oalders --release HTTP-Message-6.36

which, will retrieve a release information details

    cpanapi --show-release --distribution HTTP-Message

which, will retrieve the latest distribution release information details

    cpanapi --show-release --distribution HTTP-Message --latest

which, will retrieve the latest release for the specified distribution

    cpanapi --show-release --author oalders --release HTTP-Message-6.36 --contributors

which, will retrieve the list of contributors for the specified distributions

    cpanapi --show-release --author oalders --release HTTP-Message-6.36 --files

which, will retrieve the list of release key files by category

    cpanapi --show-release --author oalders --release HTTP-Message-6.36 --interesting-files

which, will retrieve the list of interesting files for the given release

    cpanapi --show-release --author oalders --release HTTP-Message-6.36 --modules

which, will retrieve the list of modules in the specified release

    cpanapi --show-release --recent

which, will retrieve the list of recent releases

    cpanapi --show-release --distribution HTTP-Message --by-version

which, will retrieve all releases by versions for the specified distribution

    cpanapi --show-release --distribution HTTP-Message --versions 6.35,6.34,6.36 --as-text

which, will retrieve all releases by versions for the specified distribution and for the specified version in text format.

or, alternatively:

    cpanapi --show-release --distribution HTTP-Message --versions 6.35 --versions 6.36 --as-text

Note that the order of the versions specified is unimportant, because the MetaCPAN API will return the release in their version descending order.

source

This will trigger an API query to the endpoint /source and retrieve the source the element specified using either author, release, path, or a specified module

For example:

    cpanapi --source --author oalders --release HTTP-Message-6.36 --path lib/HTTP/Message.pm

which, will retrieve the source of the element specified by the release and path

    cpanapi --source --module HTTP::Message

which, will retrieve the source of the element specified by the module

Note that the author ID is case insensitive.

suggest

This will trigger an API query to the endpoint /search/autocomplete/suggest and retrieve abridged release information.

For example:

    cpanapi --suggest --query HTTP

top-uploaders

This will trigger an API query to the endpoint /release/top_uploaders and retrieve the list of the most active authors and display it on the terminal as a chart.

For example:

    cpanapi --top-uploaders --range monthly

Possible options to use are:

range

A string specifying the result range. Valid values are all, weekly, monthly or yearly. It defaults to weekly
size

An integer to specify the size of the data returned.

OPTIONS

agg

Array. This specifies an array of distributions. This is used with --favorite

For example:

    cpanapi --favorite --agg HTTP-Message --agg DBI

You can also use alternatively aggregate:

    cpanapi --favorite --aggregate HTTP-Message --aggregate DBI

as-markdown

Boolean. When enabled, the result, when applicable, will be returned as text/x-markdown. Defaults to false.

For example:

    cpanapi --pod --author oalders --release HTTP-Message-6.36 --path lib/HTTP/Message.pm --as-markdown

    cpanapi --pod --module HTTP::Message --as-markdown

as-text

Boolean. When enabled, the result, when applicable, will be returned as text/plain. Defaults to false.

For example:

    cpanapi --diff --distribution HTTP-Message --as-text

    cpanapi --show-release --distribution HTTP-Message --versions v0.30.5,v0.31.0 --as-text

author

String. This specifies an author or a Pause account ID, such as OALDERS

For example:

    cpanapi --changes --author oalders --release HTTP-Message-6.36

by-version

Boolean. When used, this enables showing release by version with the MetaCPAN API endpoint /release/versions

For example:

    cpanapi --show-release --distribution HTTP-Message --by-version

which, will return the list of all releases with its version for the specified distribution

cache-file

File path. This specifies a file path to a JSON file that will be used instead of issuing a live HTTP request.

For example:

    cpanapi --show-module HTTP::Message --join author --join release --cache-file /some/where/module.json

debug

Integer. This specifies the level of verboseness and is used for debugging purposes.

The higher, the more debugging information will be displayed.

dev

Boolean. When this option is enabled, it indicates development versions are acceptable.

This is used in conjonction with --download-url

For example:

    cpanapi --download-url --module HTTP::Message -dev --version ">6.30, <=6.36"

dir

String. This specifies a directory path relative to a given release.

For example:

    cpanapi --show-file --author oalders --release HTTP-Message-6.36 --dir lib/HTTP

distribution

String. This specifies a distribution name.

For example:

    cpanapi --activity --distribution HTTP-Message --interval 1M

es

The file path to a JSON file containing the details of an ElasticSearch query that will be used to send to the MetaCPAN REST API.

For example:

    cpanapi --search-author --es /some/where/es-author-search.json

id

String. This is used to specify an ID, such as a CPAN ID a.k.a. an author ID. Something like OALDERS

You can repeat it to specify more than one ID.

For example:

    cpanapi --show-author --id oalders --id jdeguest

interval

String. This is the interval used for aggregate value for release activity. See activity

Possible values are an integer directly followed by one of y (year), M (month), w (week), d (day), h (hour), m (minute), and s (second).

Default value is 1M, i.e. 1 month.

For example:

    cpanapi --activity --new --interval 1w

which will show as a text chart the 1 week aggregate value for the new releases over the past 24 months.

leaderboard

Boolean. When enabled, this, in conjonction with --favorite, will trigger a query to get the top most favorite distributions.

    cpanapi --favorite --leaderboard

which will display a chart on the terminal.

max

Integer. Specifies the maximum length to show. This is used to set the maximum number of lines for the Changes file.

Set it to -1 to show all lines.

For example:

    cpanapi --changes --author oalders --release HTTP-Message-6.36 --max 12

This will show the change object and only the first 12 lines of the Changes file content.

module

String, This specifies a module, such as HTTP::Message

For example:

    cpanapi --activity --module HTTP::Message --interval 1M

which will show as a text chart the 1 month aggregate value for the releases over the past 24 months that depend on the specified module

new

Boolean. When enabled, this is used to get the new data only. This is currently used to get the new releases activity.

For example:

    cpanapi --activity --new --interval 1w

which will show as a text chart the 1 week aggregate value for the new releases over the past 24 months.

order

String. This specifies the direction with which to sort the result.

This can be either asc or desc and defaults to asc when sort is used with regular expression search. See "regexp"

For example:

    cpanapi --search-author --regexp "OA.*" --sort name --order asc

page

Integer. This specifies the result page to return. This defaults to 1.

path

String. This specifies a file or directory path relative to a given release.

For example:

    cpanapi --show-file --author oalders --release HTTP-Message-6.36 --path lib/HTTP/Message.pm

or, for a directory:

    cpanapi --show-file --author oalders --release HTTP-Message-6.36 --path lib/HTTP

prefix

String. This specifies the initial characters to search for in a Pause account ID.

For example:

    cpanapi --search-author --prefix O

This will retrieve all authors whose ID starts with the letter O

query

String. A simple search query.

For example:

    cpanapi --search-author --query "OA*" --sort name --order asc

range

A string specifying the result range. Valid values are all, weekly, monthly or yearly. It defaults to weekly

For example:

    cpanapi --top-uploaders --range weekly --size 20

recent

Boolean. When enabled, this will, in conjonction with --favorite, trigger a query to show the most recently favorited distributions.

For example:

    cpanapi --favorite --recent

regexp

String. This specifies a regular expression to be used for searching.

For example:

    cpanapi --search-author --regexp "OA.*" --sort name --order asc

This would issue an ElasticSearch query to the CPAN REST API.

save

String. This takes a file path where to save the JSON payload received by the MetaCPAN REST API.

This is useful for debugging or to take a peek.

You can also use export or save-as instead of save

For example:

    cpanapi --search-author --query "OA*" --save /some/where/cpan-author.json

show or no-show

Boolean. Enables or disables the output of formatted data on STDOUT. Defaults to true.

Sometimes, you may want to not output the result of the query to the MetaCPAN API, such as when you just want to save the result to a file.

Foe example:

    cpanapi --search-author --query "OA*" --save /some/where/cpan-author.json --no-show

size

Integer. This specifies the number of elements returned in one page of results. Usually, this defaults to 10, but it depends on the endpoint.

sort

String. This specifies the field to sort the dataset with.

For example:

    cpanapi --search-author --regexp "OA.*" --sort name --order asc

stdin

Boolean. When used, this will enable receiving the ElasticSearch JSON data on the STDIN

For example:

    cat /some/where/es.json | cpanapi --search-author --stdin

    cpanapi --search-author --stdin

then paste data, like:

    {
       "query" : {
          "regexp" : {
             "pauseid" : "OA.*"
          }
       }
    }

finally, enter ctrl-D

type

String. This specifies a type and is used in conjonction with --history

user

String. This specifies a MetaCPAN user, such as FepgBJBZQ8u92eG_TcyIGQ

For example:

    cpanapi --show-author --user FepgBJBZQ8u92eG_TcyIGQ

or with multiple user IDs:

    cpanapi --show-author --user FepgBJBZQ8u92eG_TcyIGQ --user 6ZuVfdMpQzy75_Mazx2_nw

version

String. This specifies a string, or one or more string range. Multiple ranges are separated by a comma.

For example:

    cpanapi --download-url --module HTTP::Message --version "6.36"

    cpanapi --download-url --module HTTP::Message --version ">6.30, <=6.36"

Possible operators are ==, !=, <=, >=, >, <, !

versions

Array. This specifies one or more versions for a distribution for which all its releases will be retrieved. This is used in conjonction with --show-release.

For example:

    cpanapi --show-release --distribution HTTP-Message --versions 6.35 --versions 6.34

If you prefer, you can provide multiple version as a comma separated value, such as:

    cpanapi --show-release --distribution HTTP-Message --versions 6.35,6.34

or, even:

    cpanapi --show-release --distribution HTTP-Message --versions "6.35,6.34"

Note that the order of the versions specified is unimportant, because the MetaCPAN API will return the release in their version descending order.

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT

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

To install Net::API::CPAN, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::API::CPAN

CPAN shell

perl -MCPAN -e shell
install Net::API::CPAN

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME cpanapi

SYNOPSIS

DESCRIPTION

COMMANDS

activity

autocomplete

changes

contributor

cover

diff

download-url

favorite

first

history

permission

pod

reverse

search-author

search-distribution

search-file

search-package

search-permission

show-author

show-distribution

show-file

show-package

show-release

source

suggest

top-uploaders

OPTIONS

agg

as-markdown

as-text

author

by-version

cache-file

debug

dev

dir

distribution

es

id

interval

leaderboard

max

module

new

order

page

path

prefix

query

range

recent

regexp

save

show or no-show

size

sort

stdin

type

user

version

versions

AUTHOR

COPYRIGHT

Module Install Instructions