CLI

=title package Zef::CLI

=subtitle The zef command line interface

Synopsis

    zef --help
    raku -e 'use Zef::CLI' install ./my-dist

Description

Acts as a script-in-module-form (for precompilation reasons). As such the following two commands are the same: zef install Foo, raku -e 'use Zef::CLI' install Foo. See `zef --help` or `raku -I. bin/zef --help` for high level information on the various commands and options.

Subroutines

sub MAIN(:$version)

multi sub MAIN(Bool :version($) where .so) {

Show the version of zef being used.

sub MAIN(:$help)

multi sub MAIN(Bool :h(:help($)))

Show the usage message.

sub MAIN('fetch', ...)

sub MAIN(
            'fetch',
            Bool :force(:$force-fetch),
            Int  :timeout(:$fetch-timeout) = %*ENV<ZEF_FETCH_TIMEOUT> // 600,
            Int  :degree(:$fetch-degree)   = %*ENV<ZEF_FETCH_DEGREE> || 5, # default different from Zef::Client,
            :$update, # Not Yet Implemented
            *@identities ($, *@)
        )

Download and extract the best matching distribution found for each @identities. Will exit 0 on success.

If $force-fetch is True then a failure to fetch something won't throw an exception.

If $fetch-timeout is set to a non-zero c<Int> zef will wait for that many seconds when fetching something before attempting to try the next matching fetching adapter.

If $fetch-degree is set zef will download up to that many distributions in parallel.

sub MAIN('test', ...)

sub MAIN(
            'test',
            Bool :force(:$force-test),
            Int  :timeout(:$test-timeout) = %*ENV<ZEF_TEST_TIMEOUT> || 3600,
            Int  :degree(:$test-degree) = %*ENV<ZEF_TEST_DEGREE> || 1,
            *@paths ($, *@)
        )

Test the distributions from the provided @paths. Will exit 0 on success.

If $force-test is True then a test failure won't throw an exception.

If $test-timeout is set to a non-zero c<Int> zef will wait for that many seconds when testing a distribution before aborting.

If $test-degree is set zef will test up to that many distributions in parallel.

sub MAIN('build', ...)

sub MAIN(
            'build',
            Bool :force(:$force-build),
            Int  :timeout(:$build-timeout) = %*ENV<ZEF_BUILD_TIMEOUT> || 3600,
            *@paths ($, *@)
        )

Build the distributions from the provided @paths. Will exit 0 on success.

If $force-build is True then a test failure won't throw an exception.

If $build-timeout is set to a non-zero c<Int> zef will wait for that many seconds when building a distribution before aborting.

sub MAIN('install', ...)

sub MAIN(
            'install',
            Bool :$fetch         = True,
            Bool :$build         = True,
            Bool :$test          = True,
            Bool :$depends       = True,
            Bool :$build-depends = $build,
            Bool :$test-depends  = $test,
            Bool :$force,
            Bool :$force-resolve = $force,
            Bool :$force-fetch   = $force,
            Bool :$force-extract = $force,
            Bool :$force-build   = $force,
            Bool :$force-test    = $force,
            Bool :$force-install = $force,
            Int  :$timeout,
            Int  :$fetch-timeout   = %*ENV<ZEF_FETCH_TIMEOUT>   // $timeout // 600,
            Int  :$extract-timeout = %*ENV<ZEF_EXTRACT_TIMEOUT> // $timeout // 3600,
            Int  :$build-timeout   = %*ENV<ZEF_BUILD_TIMEOUT>   // $timeout // 3600,
            Int  :$test-timeout    = %*ENV<ZEF_TEST_TIMEOUT>    // $timeout // 3600,
            Int  :$install-timeout = %*ENV<ZEF_INSTALL_TIMEOUT> // $timeout // 3600,
            Int  :$degree,
            Int  :$fetch-degree   = %*ENV<ZEF_FETCH_DEGREE> || $degree || 5, # default different from Zef::Client
            Int  :$test-degree    = %*ENV<ZEF_TEST_DEGREE>  || $degree || 1,
            Bool :$precompile-install,
            Bool :$dry,
            Bool :$upgrade,# Not Yet Implemented
            Bool :$deps-only,
            Bool :$serial,
            Bool :$contained,
            :$update,
            :$exclude,
            :to(:$install-to) = %*ENV<ZEF_INSTALL_TO> // $CONFIG<DefaultCUR>,
            *@wants ($, *@)
        )

Fetch, extract, build, test, and install @wanted distributions and their prerequisites. If @wanted contains a value of - then each line of STDIN will be added to @wanted.

If $fetch is set to False then the fetch phase will be skipped.

If $build is set to False then the build phase will be skipped.

If $test is set to False then the test phase will be skipped.

If $depends is set to False then runtime dependencies will be ignored.

If $build-depends is set to False then build dependencies will be ignored.

If $test-depends is set to False then test dependencies will be ignored.

If $force is set to True then zef will treat any failures as successes, potentially allowing progress to continue on failure.

If $force-resolve is set to True then zef will treat any name resolution failures as successes, potentially allowing progress to continue on failure.

If $force-fetch is set to True then zef will treat any fetch failures as successes, potentially allowing progress to continue on failure.

If $force-extract is set to True then zef will treat any extract failures as successes, potentially allowing progress to continue on failure.

If $force-build is set to True then zef will treat any build failures as successes, potentially allowing progress to continue on failure.

If $force-test is set to True then zef will treat any test failures as successes, potentially allowing progress to continue on failure.

If $force-install is set to True then zef will treat any install failures as successes, potentially allowing progress to continue on failure.

If $timeout is set to a non-zero c<Int> zef will wait for that many seconds when executing a given action for a specific distribution before aborting.

If $fetch-timeout is set to a non-zero c<Int> zef will wait for that many seconds when fetching something before attempting to try the next matching fetching adapter.

If $build-timeout is set to a non-zero c<Int> zef will wait for that many seconds when building a distribution before aborting.

If $test-timeout is set to a non-zero c<Int> zef will wait for that many seconds when testing a distribution before aborting.

If $install-timeout is set to a non-zero c<Int> zef will wait for that many seconds when installing a distribution before aborting.

If $fetch-degree is set zef will download up to that many distributions in parallel.

If $test-degree is set zef will test up to that many distributions in parallel.

If $precompile-install is set to False then Raku code won't be precompiled during installation.

If $dry is set to True then the final step of actually installing the distribution will be skipped and considered a success.

If $deps-only is set to True then only the dependencies of the requested identities will be processed.

If $serial is set to True then zef will install each distribution after it passes its own tests. By default this is False and means nothing will be installed unless all distributions passed their tests.

If $contained is set to True (and combined with :$install-to) zef will install all distributions to a location, including those that might otherwise already be installed and visible in another location (BETA)

If $update is set to True it will force an update of all ecosystem / repository indexes. If $update is set to a Str or Array[Str] it will only update the repositories that match the given names.

If $exclude If $exclude is set to a Str or Array[Str] then any matching dependency will be ignored.

If $to/:$install-to is set to a Str or Array[Str] then distributions will be installed to all of those CompUnit::Repository. The short names site home vendor can be used to reference their associated repository, otherwise a file path can be given to use a custom location. By default this is set to the zef-specific value auto which makes zef use the site repository if the user has write access and the home otherwise.

sub MAIN('uninstall', ...)

sub MAIN(
            'uninstall',
            :from(:$uninstall-from),
            *@identities ($, *@)
        )

Uninstall distributions matching @identities from any visible repository.

If $uninstall-from is set to a Str or Array[Str] then the uninstall will apply to those repositories instead of all visible ones.

sub MAIN('search', ...)

multi sub MAIN('search', Int :$wrap = False, :$update, *@terms ($, *@))

Does a basic substring search for any of @terms and returns any matching distributions.

If $wrap is set to True then the generated table won't wrap (nyi -- need to detect terminal width again), and if set to an Int limit the generated table to that many characters wide.

If $update is set to True it will force an update of all ecosystem / repository indexes. If $update is set to a Str or Array[Str] it will only update the repository that matches the given names.

sub MAIN('list', ...)

multi sub MAIN('list', Int :$max?, :$update, Bool :i(:$installed), *@at)

List all distributions from all known repositories.

If $max is set then only that many results will be returned from each repository.

If $i/$installed is set to True then only installed distributions will be listed.

If @at is set to a Array[Str] it will only list distributions from the repositories that match the given names.

sub MAIN('depends', ...)

multi sub MAIN(
            'depends',
            $identity,
            Bool :$depends       = True,
            Bool :$test-depends  = True,
            Bool :$build-depends = True,
        )

List the dependencies of the given $identity.

If $depends is set to False then runtime dependencies will be ignored.

If $build-depends is set to False then build dependencies will be ignored.

If $test-depends is set to False then test dependencies will be ignored.

sub MAIN('rdepends', ...)

multi sub MAIN(
            'rdepends',
            $identity,
            Bool :$depends       = True,
            Bool :$test-depends  = True,
            Bool :$build-depends = True,
        )

List the reverse dependencies of the given $identity.

If $depends is set to False then runtime dependencies will be ignored.

If $build-depends is set to False then build dependencies will be ignored.

If $test-depends is set to False then test dependencies will be ignored.

sub MAIN('info', ...)

multi sub MAIN('info', $identity, :$update, Int :$wrap = False)

List detailed information about the best match for $identity.

If $wrap is set to True then the generated table won't wrap (nyi -- need to detect terminal width again), and if set to an Int limit the generated table to that many characters wide.

sub MAIN('browse', ...)

multi sub MAIN('browse', $identity, $url-type where * ~~ any(<homepage bugtracker source>), Bool :$open = True)

Open a browser to the $url-type resource of the best matching distribution for $identity.

If $open is set to False then a browser window won't be opened, instead just outputting the url to the terminal.

sub MAIN('update', ...)

multi sub MAIN('update', *@names)

Update all ecosystem / repository indexes.

If @names is set to a Str or Array[Str] it will only update the repositories that match the given names.

sub MAIN('nuke', ...)

multi sub MAIN('nuke', Bool :$confirm, *@names ($, *@))

Delete everything for @names, where @names can be a core repository name (site home vendor), or a config directory reference (StoreDir TempDir).

If $confirm is set to False then zef will not prompt to confirm deletion.