{"id":13609364,"url":"https://github.com/babashka/neil","last_synced_at":"2025-10-09T06:16:31.246Z","repository":{"id":37025319,"uuid":"410909184","full_name":"babashka/neil","owner":"babashka","description":"A CLI to add common aliases and features to deps.edn-based projects","archived":false,"fork":false,"pushed_at":"2024-12-09T12:18:37.000Z","size":310,"stargazers_count":432,"open_issues_count":24,"forks_count":29,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-10-09T06:16:30.803Z","etag":null,"topics":["babashka","clojure","deps-edn"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/babashka.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-09-27T14:05:03.000Z","updated_at":"2025-09-23T01:44:38.000Z","dependencies_parsed_at":"2023-10-10T15:28:42.230Z","dependency_job_id":"2539fae4-6487-4e16-a49e-55e570ddcce6","html_url":"https://github.com/babashka/neil","commit_stats":null,"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"purl":"pkg:github/babashka/neil","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babashka%2Fneil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babashka%2Fneil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babashka%2Fneil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babashka%2Fneil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/babashka","download_url":"https://codeload.github.com/babashka/neil/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/babashka%2Fneil/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000850,"owners_count":26082950,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["babashka","clojure","deps-edn"],"created_at":"2024-08-01T19:01:34.365Z","updated_at":"2025-10-09T06:16:30.967Z","avatar_url":"https://github.com/babashka.png","language":"Clojure","funding_links":[],"categories":["Clojure"],"sub_categories":[],"readme":"# neil\n\nA CLI to add common aliases and features to `deps.edn`-based projects.\n\n## Introduction\n\nSee the [New Clojure project quickstart](https://blog.michielborkent.nl/new-clojure-project-quickstart.html) blog post for a gentle introduction into `neil`.\n\n## Installation\n\n### Homebrew (Linux and macOS)\n\n```\n$ brew install babashka/brew/neil\n```\n\n### Scoop (Windows)\n\n```\n$ scoop bucket add scoop-clojure https://github.com/littleli/scoop-clojure\n$ scoop install neil\n```\nFor detailed information about scoop installer check [scoop-clojure](https://github.com/littleli/scoop-clojure).\n\n### Nix\n\n```bash\n$ nix-shell -p neil\n\n# Alternatively, if your nix channel doesn't have neil yet:\n$ nix-shell -I nixpkgs=channel:nixos-unstable -p neil\n```\n### [BBin](https://github.com/babashka/bbin/)\n\n```bash\n$ bbin install io.github.babashka/neil\n```\n\n### Clojure\n\nIf possible, use the above methods instead, as this would have a much slower startup. Another problem is that the global `:neil` alias can be overridden by a local one, making it [impossible to use inside the neil repo itself](https://github.com/babashka/neil/issues/246).\n\nAdd the following alias to your global or project-local `deps.edn`:\n\n``` clojure\n:neil {:deps {io.github.babashka/neil {:git/tag \"v0.3.68\"\n                                       :git/sha \"78ffab1\"}}\n       :main-opts [\"-m\" \"babashka.neil\"]}\n```\n\nThen invoke `clj -M:neil`.\n\n### Manual\n\n- Install [babashka](https://github.com/babashka/babashka#installation)\n- Download the [`neil`](https://raw.githubusercontent.com/babashka/neil/main/neil) script to somewhere on your `PATH`. In Windows, also\n  download the [`neil.bat`](https://raw.githubusercontent.com/babashka/neil/main/neil.bat) script and place it in the `PATH`.\n\n## Status\n\nAs we're still finding out the best UX, `neil` may undergo breaking changes from\nversion to version.\n\n## Usage\n\nType `neil` to see the help:\n\n```\nUsage: neil \u003csubcommand\u003e \u003coptions\u003e\n\nMost subcommands support the options:\n  --alias      Override alias name.\n  --deps-file  Override deps.edn file name.\n\nSubcommands:\n\nadd\n  dep    Alias for `neil dep add`.\n  test   adds cognitect test runner to :test alias.\n  build  adds tools.build build.clj file and :build alias.\n  kaocha adds kaocha test runner to :kaocha alias.\n  nrepl  adds nrepl server to :nrepl alias.\n\ndep\n  add: Adds --lib, a fully qualified symbol, to deps.edn :deps.\n    Run `neil dep add --help` to see all options.\n\n  search: Search Clojars for a string in any attribute of an artifact\n    Run `neil dep search --help` to see all options.\n\n  upgrade: Upgrade libs in the deps.edn file.\n    Run `neil dep upgrade --help` to see all options.\n\n  versions: List available versions of a library (Clojars libraries only)\n    Run `neil dep versions -h` to see all options.\n\n  update: Alias for `upgrade`.\n\nlicense\n  list   Lists commonly-used licenses available to be added to project. Takes an optional search string to filter results.\n  search Alias for `list`\n  add    Writes license text to a file\n    Options:\n    --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.\n    --file    The file to write. Defaults to 'LICENSE'.\n\nnew\n  Create a project using deps-new\n    Run `neil new --help` to see all options.\n\nversion\n  Commands for managing the :version key in the deps.edn project config.\n    Run `neil version --help` to see all options.\n\ntest\n  Run tests. Assumes `neil add test`. Run `neil test --help` to see all options.\n```\n\n### add dep\n\nThis will add the newest version of clj-kondo to the `:deps` map in `deps.edn`:\n\n```\n$ neil add dep :lib clj-kondo/clj-kondo\n```\n\nThe `:lib` keyword may be elided if the libname is the first argument after `dep`:\n\n```\n$ neil add dep clj-kondo/clj-kondo\n```\n\nThe `add dep` command will always overwrite an existing dependency.\n\nTo add a git library from Github you can use `:sha` to provide a SHA or\n`:latest-sha` to pick the latest sha from the default branch:\n\n```\n$ neil add dep org.babashka/sci :latest-sha true\n```\n\n### add build\n\nTo add [tools.build](https://clojure.org/guides/tools_build) related features, use:\n\n```\n$ neil add build :deps-deploy true\n```\n\nAfter that you can run tasks like:\n\n```\n$ clojure -T:build uber\n$ clojure -T:build deploy\n```\n\nIf 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](https://blog.michielborkent.nl/new-clojure-project-quickstart.html).\n\n### add test\n\n``` clojure\n$ neil add test\n```\n\nThis will add the Cognitect\n[test-runner](https://github.com/cognitect-labs/test-runner) to your `deps.edn`\nso you can execute:\n\n``` clojure\n$ clojure -X:test\n```\n\nA similar option is supported for\n[kaocha](https://github.com/lambdaisland/kaocha):\n\n```\n$ neil add kaocha\n```\n\nTo change the alias you can provide an option like:\n\n```\n$ neil add kaocha :alias kaocha2\n```\n\n### dep search\n\nSearch Clojars for a string in any attribute of an artifact:\n\n```\n$ neil dep search \"babashka.nrepl\"\n:lib babashka/babashka.nrepl :version 0.0.6\n```\n\nNote 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:\n\n```\n$ neil dep search \"babashka/babashka.nrepl\"\nUnable to find babashka/babashka.nrepl on Clojars.\n```\n\nBut a search string can be matched in a library's description:\n\n```\n$ neil dep search \"test framework\"\n```\nwill return libraries with 'test framework' in their description.\n\n### license list\n\nList/search for licenses that can be added to a project with `neil`. This functionality uses Github's license API,\nwhich is also used by [choosealicense.com](https://choosealicense.com/). With no search term, a list of\ncommonly-used licenses is returned:\n\n```\n$ neil license list\n:license agpl-3.0 :name GNU Affero General Public License v3.0\n:license apache-2.0 :name Apache License 2.0\n...\n```\n\nA search term can be added to filter the commonly-used list with a case-insensitive search against the license name:\n\n```\n$ neil license list \"lesser general\"\n:license lgpl-2.1 :name GNU Lesser General Public License v2.1\n```\n\nThe full collection of available licenses can be found in the [license API repo](https://github.com/github/choosealicense.com/tree/gh-pages/_licenses).\n\n`license search` is an alias for `license list`.\n\n### license add\n\nRetrieve license text from Github's license API and write it to a file. See the `license list` help for details on available licenses.\n\n```\n$ neil license add :license mit :file myproj/license.txt\n```\n\nWill 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,\nand `:file` defaults to LICENSE, so a minimal usage:\n\n```\n$ neil license add epl-1.0\n```\n\nWill create a LICENSE file in the current directory with the EPL 1.0 text.\n\n## Emacs Integration\n[![MELPA status](https://melpa.org/packages/neil-badge.svg)](https://melpa.org/#/neil)\n\n[neil.el](https://github.com/babashka/neil/blob/main/neil.el) is a companion Emacs package.\n\n### Installation\nLoad it using your preferred Emacs package manager, e.g., for Doom Emacs:\n\n```emacs-lisp\n;; packages.el\n\n(package! neil :recipe (:host github :repo \"babashka/neil\" :files (\"*.el\")))\n\n;; config.el\n\n(use-package! neil\n  :config\n  (setq neil-prompt-for-version-p nil\n        neil-inject-dep-to-project-p t))\n\n;; by default it attempts to find \"neil\" somewhere in the $PATH,\n;; but you can set the executable explicitly, e.g.,\n(setq neil-executable-path \"neil-cmd\")\n;; or:\n(setq neil-executable-path \"clj -M:neil\")\n;; see the full list of customizations below\n```\nFor a built-in package.el manager you can install it from from [MELPA](https://melpa.org/#/neil) with `M-x package-install` or with `:ensure` keyword from `use-package`.\n\n```emacs-lisp\n(use-package neil\n  :defer t\n  :ensure t\n  :custom\n  (neil-prompt-for-version-p nil)\n  (neil-inject-dep-to-project-p t))\n```\n\n### Usage\n\nSo far, neil.el provides a command `M-x neil-find-clojure-package` that searches for the packages (using `neil dep search`), and generates a dependency string for different Clojure project types.\n\n### Customization\n\n* `neil-prompt-for-version-p` (default `t`)\n\n  When non-nil, select from available versions of a lib. Otherwise, use the latest found.\n\n* `neil-inject-dep-to-project-p` (default `nil`)\n\n    When non-nil, try to add library dependency to current project. Otherwise, simply store the dependency string in the `kill-ring'. Works only for deps.edn projects.\n\n* `neil-executable-path` (default `nil`)\n\n    If nil, tries to find neil executable in the PATH. Otherwise uses the given value.\n\n\n## Github's Rate Limit\n\nGithub's API has a 60 hit/hour rate-limit. The workaround for this is creating a\n[personal access\ntoken](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)\nand setting two env vars:\n\n- `NEIL_GITHUB_USER`\n- `NEIL_GITHUB_TOKEN`\n\n## Roadmap\n\n- Add `bb.edn`-related features for invoking `test` and `build` tasks\n- Option to add `cljs-test-runner`\n\n## Contributing\n\nIf this project shows potential to you, I'd be happy to discuss and receive\ncontributions.\n\n## Dev\n\nSee\n[neil.rb](https://github.com/babashka/homebrew-brew/blob/main/Formula/neil.rb)\nfor the brew Formula. You can install this formula locally with:\n\n```\n$ brew reinstall --build-from-source ./neil.rb\n```\n\nOr install a development version with [bbin][bbin]:\n\n```\n$ bbin install . --as neil-dev --main-opts '[\"-m\" babashka.neil/-main]'\n```\n\nYou can choose your own binary name with the `--as YOUR_BINARY` option.\nRebuilding is not required when installing with bbin - any changes to\n`src/babashka/neil.clj` will count the next time you run `neil-dev`\n(`YOUR_BINARY`).\n\n[bbin]: https://github.com/babashka/bbin\n\n## License\n\nCopyright © 2022 Michiel Borkent\n\nDistributed under the MIT License. See LICENSE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbabashka%2Fneil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbabashka%2Fneil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbabashka%2Fneil/lists"}