A CLI to add common aliases and features to deps.edn
-based projects.
See the New Clojure project quickstart blog post for a gentle introduction into neil
.
$ brew install babashka/brew/neil
$ scoop bucket add scoop-clojure https://github.com/littleli/scoop-clojure
$ scoop install neil
For detailed information about scoop installer check scoop-clojure.
$ nix-shell -p neil
# Alternatively, if your nix channel doesn't have neil yet:
$ nix-shell -I nixpkgs=channel:nixos-unstable -p neil
Add the following alias to your global or project-local deps.edn
:
:neil {:deps {io.github.babashka/neil {:git/tag "v0.1.41"
:git/sha "77288d4"}}
:main-opts ["-m" "babashka.neil"]}
Then invoke clj -M:neil
.
- Install babashka
- Download the
neil
script to somewhere on yourPATH
. In Windows, also download theneil.bat
script and place it in thePATH
.
As we're still finding out the best UX, neil
may undergo breaking changes from
version to version.
Type neil
to see the help:
Usage: neil <subcommand> <options>
Most subcommands support the options:
--alias Override alias name.
--deps-file Override deps.edn file name.
Subcommands:
add
dep Alias for `neil dep add`.
test adds cognitect test runner to :test alias.
build adds tools.build build.clj file and :build alias.
kaocha adds kaocha test runner to :kaocha alias.
nrepl adds nrepl server to :nrepl alias.
dep
add: Adds --lib, a fully qualified symbol, to deps.edn :deps.
Run `neil dep add --help` to see all options.
search: Search Clojars for a string in any attribute of an artifact
Run `neil dep search --help` to see all options.
upgrade: Upgrade libs in the deps.edn file.
Run `neil dep upgrade --help` to see all options.
versions: List available versions of a library (Clojars libraries only)
Run `neil dep versions -h` to see all options.
update: Alias for `upgrade`.
license
list Lists commonly-used licenses available to be added to project. Takes an optional search string to filter results.
search Alias for `list`
add Writes license text to a file
Options:
--license The key of the license to use (e.g. epl-1.0, mit, unlicense). --license option name may be elided when license key is provided as first argument.
--file The file to write. Defaults to 'LICENSE'.
new
Create a project using deps-new
Run `neil new --help` to see all options.
version
Commands for managing the :version key in the deps.edn project config.
Run `neil version --help` to see all options.
test
Run tests. Assumes `neil add test`. Run `neil test --help` to see all options.
This will add the newest version of clj-kondo to the :deps
map in deps.edn
:
$ neil add dep :lib clj-kondo/clj-kondo
The :lib
keyword may be elided if the libname is the first argument after dep
:
$ neil add dep clj-kondo/clj-kondo
The add dep
command will always overwrite an existing dependency.
To add a git library from Github you can use :sha
to provide a SHA or
:latest-sha
to pick the latest sha from the default branch:
$ neil add dep org.babashka/sci :latest-sha true
To add tools.build related features, use:
$ neil add build :deps-deploy true
After that you can run tasks like:
$ clojure -T:build uber
$ clojure -T:build deploy
If you didn't use the full app template when starting your project, then you'll need to configure a couple things in order to get a working uberjar. See the uberjar section here.
$ neil add test
This will add the Cognitect
test-runner to your deps.edn
so you can execute:
$ clojure -X:test
A similar option is supported for kaocha:
$ neil add kaocha
To change the alias you can provide an option like:
$ neil add kaocha :alias kaocha2
Search Clojars for a string in any attribute of an artifact:
$ neil dep search "babashka.nrepl"
:lib babashka/babashka.nrepl :version 0.0.6
Note that Clojars stores the namespace and name of a library as separate attributes, so searching for a ns-qualified library will not necessarily return any matches:
$ neil dep search "babashka/babashka.nrepl"
Unable to find babashka/babashka.nrepl on Clojars.
But a search string can be matched in a library's description:
$ neil dep search "test framework"
will return libraries with 'test framework' in their description.
List/search for licenses that can be added to a project with neil
. This functionality uses Github's license API,
which is also used by choosealicense.com. With no search term, a list of
commonly-used licenses is returned:
$ neil license list
:license agpl-3.0 :name GNU Affero General Public License v3.0
:license apache-2.0 :name Apache License 2.0
...
A search term can be added to filter the commonly-used list with a case-insensitive search against the license name:
$ neil license list "lesser general"
:license lgpl-2.1 :name GNU Lesser General Public License v2.1
The full collection of available licenses can be found in the license API repo.
license search
is an alias for license list
.
Retrieve license text from Github's license API and write it to a file. See the license list
help for details on available licenses.
$ neil license add :license mit :file myproj/license.txt
Will write the MIT license to the file myproject/license.txt. The :license
keyword can be left out if the license key is the first argument,
and :file
defaults to LICENSE, so a minimal usage:
$ neil license add epl-1.0
Will create a LICENSE file in the current directory with the EPL 1.0 text.
neil.el is a companion Emacs package.
Load it using your preferred Emacs package manager, e.g., for Doom Emacs:
;; packages.el
(package! neil :recipe (:host github :repo "babashka/neil" :files ("*.el")))
;; config.el
(use-package! neil
:config
(setq neil-prompt-for-version-p nil
neil-inject-dep-to-project-p t))
Github's API has a 60 hit/hour rate-limit. The workaround for this is creating a personal access token and setting two env vars:
NEIL_GITHUB_USER
NEIL_GITHUB_TOKEN
- Add
bb.edn
-related features for invokingtest
andbuild
tasks - Option to add
cljs-test-runner
If this project shows potential to you, I'd be happy to discuss and receive contributions.
See neil.rb for the brew Formula. You can install this formula locally with:
$ brew reinstall --build-from-source ./neil.rb
Or install a development version with bbin:
$ bbin install . --as neil-dev --main-opts '["-m" babashka.neil/-main]'
You can choose your own binary name with the --as YOUR_BINARY
option.
Rebuilding is not required when installing with bbin - any changes to
src/babashka/neil.clj
will count the next time you run neil-dev
(YOUR_BINARY
).
Copyright © 2022 Michiel Borkent
Distributed under the MIT License. See LICENSE.