A Deno registry browser in the terminal
kopo
is a cli tool, which helps you browse the Deno registries in your terminal in an easy, nicely presented way.
It supports deno.land/x
and x.nest.land
by default, but also enables you to use addons, to access different registries.
kopo
is intended to be as an installed user script. For that, run:
deno install --unstable --allow-net -f --name kopo --location https://kopo.mod.land https://deno.land/x/kopo@v0.1.1/mod.ts
To just try it out, run the following command:
deno run --unstable --allow-net --location https://kopo.mod.land https://deno.land/x/kopo@v0.1.1/mod.ts
- browse the registries
- search through registries for a keyword/specific module
- get a specific module's info, eg: description, stars, repo, versions, readme
- print a module's readme as a formatted markdown text with charmd
- show what flags a module requires
- An addon system, to access private or not yet added registries.
- Persisted settings, like theme, disabled registries, other preferences + export, import of it
kopo
's features can be accessed in two may separate ways.
- Use it as an interactive application with a menu system
- Issue simple commands and get only what you need in the cli
If installed with the command above, you simply need to issue the kopo
command in your terminal, than the main menu should appear:
After that, you can navigate the menu using the โ โ or w s buttons. (On windows you can't use the arrows currently :/ issue)
Select one from the enabled registries, than browse the paginated modules list or search for a term.
Issue a global search in all registries.
Use the @
and a version to search for a specific version, like kopo@v0.0.2
.
If the search term isn't a modules name, you can search the registries for that term with the options at the bottom.
After you select a module, you will see it's info:
From here, you can print it's README as a formatted MarkDown(using charmd) if one was found for it, get details about its flags, see other versions of it or see which other registries have this module registered.
If the --location
flag was provided, you can access the settings, where you can tailor some features to your likings:
๐ง The API needs work, so it's bound to be changed ๐ง
Your starting point is:
kopo search
Without any following parameters, the search menu will pop up for you.
If you want to search for a specific search term eg charmd
issue:
kopo search charmd
If you know the module's name you are searching for add --exact
or -e
flag.
kopo search kopo -e
This will get the first exact match from the first registry and display the modules info for you. Also, you can add -v [exact version]
to get a specific version of the module.
If you have -e
you can add --readme
or --read-raw
so the modules README will be printed instead.
kopo search charmd -e --readme
Adding --flags
will print the module's flags described in the readme if found.
kopo search kopo -e --flags
Adding --json
flag for any of the above commands, will result in a formatted json output, instead of formatted text.
kopo search charmd -e --json
You can export or import your settings which are stored in localStorage.
If
--allow-read
and--allow-write
flags are not provided at install, the script will request it in runtime.
kopo settings export settings.json
kopo settings import settings.json
Currently deno.land/x
and x.nest.land
is supported by default. However, you can use addons to integrate with other, not yet supported or private registries.
For this, first you need to have path (remote or local) to the registry addon, which should extend
the Registry
class. (example)
With that, you can add this path to your exported settings json and import it back into the app or use the -r
flag for any of the commands.
settings.json
[
{
"key": "registry_addons",
"value": [
"https://raw.githubusercontent.com/littletof/kopo-cli/remaster/examples/example_registry_addon.ts"
]
}
]
This flag will override which registries kopo
will use during its runtime.
kopo -r deno,nest,https://raw.githubusercontent.com/littletof/kopo-cli/remaster/examples/example_registry_addon.ts
Use
file:///
prefix for any local files:file:///C:/example.ts
If the -r
flag is used, no registry, that is not defined will be accessible.
Also, if -r
is not used, you can enable/disable your builtin and through settings added registries in the application.
For example, if you want to search only the nest
registry you can use:
kopo search kopo -e -r nest --readme
๐ง This is just an experimental feature currently ๐ง
This proposes a concept, where each module describes what its required and optional flags are in a parseable way.
The parser is here
Currently it searches for markdown table rows, which contain 2 or 3 columns.
- The first column needs to contain the flag inside backticks like (
--unstable
). Things can be before it in the column, but only spaces are allowed after it. - The second column indicates, whether the flag is required (
*
,Yes
oryes
) or optional (empty). Putting_
in this column tells the parser to ignore the row. - The optional third column can serve as a description why the flag is needed.
A table could look something like this:
Flag | Required | Reason |
---|---|---|
๐ง --unstable |
* | Needed for Cliffy to work |
๐ --allow-net |
* | To fetch data from the repos |
๐ฐ --location |
To save settings. https://kopo.mod.land |
|
๐ --allow-read |
_ | Needed for cache info |
๐พ --allow-write |
_ | Save favourites |
โฑ --allow-hrtime |
_ | Allows precise benchmarking |
โ --allow-run |
_ | Needed for feature x |
๐งญ --allow-env |
_ | Needed to access your ENV |
๐งฉ --allow-plugin |
_ | Deprecated Old plugin system |
๐งฉ --allow-ffi |
_ | For Deno plugin system |
๐ฎ --allow-all |
_ | It should never be required |
Also keep in mind, that you can hide this inside a comment if you dont find a proper place for it in your readme, inside the
<!--
-->
tags, but than only the tools processing your readme can see it.
There is a small util that you can use to test your file for the flags. It can be found here.
To use it simply run:
deno run --allow-read https://deno.land/x/kopo@v0.1.1/flag_checker.ts ./README.md
or for remote files:
deno run --allow-net https://deno.land/x/kopo@v0.1.1/flag_checker.ts https://raw.githubusercontent.com/littletof/kopo-cli/master/README.md
Issues, pull requests and feedback are always welcome.
- add module import url processing for search, etc..
- more tests
Copyright 2020- Szalay Kristรณf. All rights reserved. MIT license.