toys 0.21.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87582d55a2f60738d19c3c4d717f93910c5cc677f5e210c8418366baf2e91921
-  data.tar.gz: f82f165fa06113b1ad398c5cb2d5e62217d860924f00e5b0d3b6172824d4a116
+  metadata.gz: ee5fe663d934949887ff7ce01289453e7b59efcc553331e2efb8a8ae949b626b
+  data.tar.gz: c34a38d893789bdb14fc159f211ac83b09a39b2d897601c961755876be2b6d28
 SHA512:
-  metadata.gz: 5a9dad0dcdd8c83d678dfe23522faaa38b62bb765e16f7b6aafce2ce014920d13addce0d32a619f4c5d80e21f8e79b40ff8c0936381169df17d080d3d2500aec
-  data.tar.gz: 0f2b4c0cc5cf87ed070d7f21d57f8a9b2051277c5651f5e4d210b9ebb2a9498df93dde3203cb54437c19f8991ed348ab3b9d59c5a944c3070aa22e09a7cdd14e
+  metadata.gz: 0fd0c5c2edfe80ede91db110a513bfe176766b4d3c8a75e378721296b8fe4c7c5681e07695fa249f9efede159ffb9feff43524d3ad085f98ca7498af9433c3d1
+  data.tar.gz: 5345ecacee610f36dd439f7adf8b1118a1cc0ecb858f19a5f3c938a5e86a33fb19be94fff5173e3170d1bac6b8ed4309fc54192f5542573e15a7109ddeaba9e2

data/CHANGELOG.md

@@ -1,5 +1,129 @@
 # Release History
 
+### v0.23.0 / 2026-09-09
+
+This is a major release, with several new features. It also includes a significant refactor of some of the underlying layers, which should be mostly invisible. It is a release candidate for the upcoming version 1.0.
+
+Highlights include:
+
+* Added the ability to treat unknown flags as positional args via the `treat_unknown_flags_as_args` DSL directive. Useful for wrapping and delegating to other commands.
+* The `do` builtin tool supports `--gem=`, `--git=`, and `--path=` flags that make additional tool sources available.
+* Running tools from within a tool should generally now be done via the new `Toys::Runner` object, now available in the runtime context, instead of via the `Toys::CLI`. The new object provides finer-grained control over error handling and verbosity.
+* Updates to error handling to improve the output and fix some long-standing issues related to tool delegation.
+* Several fixes to bundler integration, especially with Bundler 4.
+
+Details follow.
+
+* Changes to tool definition:
+    * Added the `treat_unknown_flags_as_args` DSL directive (and the corresponding `ToolDefinition#treat_unknown_flags_as_args` setter and `ToolDefinition#unknown_flags_are_args?` query), which redirects unrecognized flags to the tool's positional arguments instead of reporting a usage error. Useful for wrapping and delegating to other commands.
+    * The `set_context_directory` DSL directive can now take Pathname arguments and handles relative paths (by expanding to absolute paths).
+    * When two or more flags are declared using the same context key, within a flag group, the flag group's requirements now evaluate correctly.
+    * A flag or optional/remaining positional argument declared with a `nil` default no longer clears default data already set for the same key by an earlier declaration.
+    * Toys now raises `Toys::ToolDefinitionError` if you attempt to "reset" a tool previously defined using a `Toys::Tool` subclass.
+    * SECURITY FIX: Toys now raises `Toys::ToolSourceError` if a tool loaded from a RubyGem attempts to load tools from the local file system.
+    * BREAKING CHANGE: Toys now raises `Toys::ToolDefintionError` if you attempt to create or descend into a subtool from a `subtool_apply` block or a middleware-based config.
+    * Caught additional cases of incorrectly located `Toys::Tool` subclasses and raised `Toys::ToolDefinitionError`
+    * Toys directory contents are loaded in deterministic (sorted) order.
+
+* Changes to tool execution:
+    * Added `Toys::Context#runner` for access to the `Toys::Runner` object. This is now the preferred way to run tools from within other tools (instead of `Toys::CLI#run`), unless you need to change the configuration.
+    * Added `Toys::Context#loader` for access to the `Toys::Loader` object.
+    * BREAKING CHANGE: `Toys::Context#context_directory`, and `Toys::Context#get` with the associated context key, now never return nil. If no context directory is set for the tool, these now return the current working directory.
+    * BREAKING CHANGE: Removed git- and gem- specific attributes from `Toys::SourceInfo` and replaced with `Toys::SourceInfo#origin`.
+    * Standard context keys and sentinels use the new class `Toys::UniqueKey`, which displays useful names in diagnostic output.
+    * Delegation now propagates the caller's verbosity to the delegate target, rather than resetting it to zero.
+    * When a tool delegates, a `SignalException` unhandled by the inner tool now propagates outward so each tool in the delegation chain gets a chance at its own `on_interrupt` / `on_signal` handler.
+    * A nested run that shares a logger with the run that called it now uses the base level already in effect for that logger, so verbosity no longer compounds across nested runs.
+    * Revamped the output and stack trace printed when an exception occurs.
+
+* Changes to shell completion:
+    * Fixed shell completion for non-flag words containing `=` or `:`: completions are now computed against the whole word, and the engine trims candidates to the span the shell will actually replace.
+    * Zsh completion now replaces the entire word rather than only the text after an `=` or `:`, matching how zsh actually handles word breaks; bash continues to break at `=` and `:`.
+    * Word-break trimming for bash now ignores `=` and `:` characters that were quoted or backslash-escaped, since the shell does not break a word at a quoted character.
+    * Subtool completion now uses the loader's configured delimiters to decide where a tool path ends, rather than a separate regex over the fragment prefix, so completing a partially typed tool path works consistently with any configured extra delimiters.
+
+* Changes to builtin tools:
+    * The `do` builtin tool supports `--gem=`, `--git=`, and `--path=` flags that make additional tool sources available.
+
+* Changes to CLI interfaces:
+    * `Toys::CLI#child` accepts `copy_sources: true`, which populates the new CLI's loader with the same sources as the original. This makes it easy to create a new CLI with additional sources on top of the current.
+    * You can get the `Toys::Runner` for a CLI using `Toys::CLI#runner`, providing a way to customize the run process more closely than using `Toys::CLI#run`.
+    * Added `add_source` method that takes an instance of the new `Toys::SourceSpec` types that describe a tool source. This method replaces the now deprecated `add_config_*` methods (although those methods will continue to be supported for a time). In general, the "config" terminology is being retired in favor of "source" which I think better describes what is going on.
+    * BREAKING CHANGE: The `config_file_name` and `config_dir_name` arguments to CLI have been renamed to `toplevel_tool_file_name` and `toplevel_tool_dir_name`, respectively, as part of a general removal of the "config" term. The old names are not aliased.
+    * BREAKING CHANGE: `Toys::CLI#run` no longer accepts the `delegated_from:` keyword argument. Tool delegation is now handled internally and its runtime is not exposed in the public interface.
+    * BREAKING CHANGE: Renamed the `StandardCLI::CONFIG_DIR_NAME` to `StandardCLI::TOPLEVEL_TOOL_DIR_NAME` and `StandardCLI::CONFIG_FILE_NAME` to `StandardCLI::TOPLEVEL_TOOL_FILE_NAME`.
+    * BREAKING CHANGE: Removed the constants `INDEX_FILE_NAME`, `PRELOAD_DIR_NAME`, `PRELOAD_FILE_NAME`, `DATA_DIR_NAME`, and `LIB_DIR_NAME` from `StandardCLI`.
+    * The `Toys::StandardCLI` constructor now takes `git_cache` and `gems_util` keyword arguments letting you customize the objects used to resolve git and gem sources.
+    * Path parameters for the methods that add sources, such as `path` and `context_directory`, can now take Pathname objects and can handle relative paths properly (by expanding them into absolute paths).
+
+* Rubygems/Bundler integration changes:
+    * Bundler integration requires Bundler 2.4 or later. This is the default on Ruby 3.2, but requires that Bundler is updated on earlier Rubies.
+    * Bundler integration properly detects provenance attributes such as `path:` and `git:`.
+    * Calling bundler integration with a nonempty group list no longer loses gems that were already loaded.
+    * Bundler integration now honors `BUNDLE_LOCKFILE` (new in Bundler 4) and stops leaking it from the modified bundle.
+
+* Other fixes
+    * Terminal mixin now raises the correct ArgumentError (instead of NameError) if given an unknown style code.
+    * `Toys::Loader#list_subtools` now ensures returned tools have been finished by their middleware. This affects listing tools not underneath the currently running tool.
+
+A number of additional minor breaking changes were made to internal interfaces in the toys-core gem classes. It is unlikely you will encounter these unless you are extending the framework, but you can see the toys-core changelog for details.
+
+### v0.22.0 / 2026-05-05
+
+Toys 0.22 is a major release focused on polish and cleanup in preparation for version 1.0. It includes a number of small breaking changes where needed to clean up the interfaces. (Note that many of the changes listed below are actually in the `toys-core` gem.)
+
+Breaking interface changes:
+
+* The `static` directive no longer "forces" creating of helper methods, instead using the same logic as the flag and argument directives. In particular, by default it will not create a method starting with underscore.
+* Removed `Toys::Settings` and moved inheritable_helper_methods to a dedicated tool attribute. Use the `basic_settings` gem if you need the old settings class.
+* `Toys::Acceptor#create` no longer takes a hash as the spec. (This was undocumented but worked previously.) To construct an object, pass the class as the main spec object, and the keyword arguments in the options.
+* `Toys::Acceptor::Enum#values` now returns the values themselves instead of a zipped array that includes strings.
+* `Toys::FlagGroup::Base` is no longer instantiable; use `Toys::FlagGroup::Optional` instead.
+* The `acceptor` and `display_name` attributes of `Toys::PositionalArg` are no longer writable and must be set in the constructor.
+* `Toys::Completion#create` no longer takes a hash as the spec. (This was undocumented but worked previously.) To construct an object, pass the class as the main spec object, and the keyword arguments in the options.
+* The `delegation_target` attribute of `Toys::ToolDefinition::DefaultCompletion` is no longer writable and must be set in the constructor.
+* You can no longer override a completion class using the `:""` key. (This was undocumented but worked previously.) Just pass a fully constructed completion object if you need a custom object.
+* The original `Module#include` method is now available in the DSL as `include_module` instead of `super_include`.
+* Template classes no longer automatically include `Toys::Context::Key`. This behavior was undocumented and inconsistent between different ways of defining templates.
+* Made `Toys::CLI#load_tool` return the block value rather than the exit_code.
+* Made `Toys::Testing#toys_load_tool` return the block value rather than the exit_code
+* Dropped undocumented `Loader#add_path_set` option to include individual source names in the relative_paths argument.
+* Renamed `use_less` in the `Toys::StandardMiddleware::ShowHelp` constructor to `use_pager`, and added support for custom pagers.
+* Renamed many of the methods in `StandardUI` to reduce confusion.
+* Removed `LoaderError` and used `ToolDefinitionError` for those cases, as it was decided that the distinction was ambiguous and dependent on internal details.
+* Removed `ContextualError#underlying_error` as it was synonymous with `cause`.
+* Consolidated `ContextualError` public interface into a single `capture` method.
+* `ArgParser::ExtraArgumentsError` now takes `:arguments` instead of `:values`, and provides an accessor for the same.
+* `ArgParser::ToolUnrecognizedError` now takes `:full_name` instead of `:values`, and provides an accessor for the same.
+* Renamed `ArgParser::UsageError#full_message` to `message_with_suggestions` to avoid overriding `Exception#full_message`.
+
+New features:
+
+* The range acceptor supports beginless and endless ranges.
+* A custom source_name can be provided to `Loader#add_path_set`, `Loader#add_git`, and `Loader#add_gem`.
+* The `:gems` mixin provides a context key for retrieving the underlying `Toys::Utils::Gems` service object.
+* The `:gems` mixin provides an explicit `Toys::Utils::Gems::ClassMethods` module defining the directives added to the tool class.
+* The `activate` and `bundle` methods in the Gems utility now return useful results.
+
+Other fixes:
+
+* The `:update` argument to the `load_git` directive had no effect if the `:as` argument was provided.
+* `FlagValueUnacceptableError` and `ArgValueUnacceptableError` have their value set correctly.
+* If a CLI has a static (shared) logger, creating a child with `logger: nil` actually clears it.
+* Removed unused `Toys::StandardMiddleware::ShowHelp::TOOL_NAME_KEY`.
+* ShowHelp middleware displays an error message instead of raising an exception when help cannot be generated due to a bad search regex.
+* `ArgParser::UsageError` is now a proper exception.
+* `ContextualError` does a better job of capturing relevant syntax errors.
+* Various minor completion system fixes.
+
+Several libraries under `toys/utils` were extracted into their own gems. The current code remains under `Toys::Utils` as a vendored copy of the external gem, so the extracted gems are not actually dependencies of Toys. The affected libraries are:
+
+* `Toys::Utils::Exec` which was extracted to the gem `exec_service`.
+* `Toys::Utils::XDG` which was extracted to the gem `simple_xdg`.
+* `Toys::Utils::GitCache` which was extracted to the gem `git_cache`.
+
+Finally, a variety of clarifications and fixes were made to the reference documentation, readme, and user's guide.
+
 ### v0.21.0 / 2026-03-23
 
 This release includes a variety of small fixes and updates toward improving product polish in preparation for a 1.0 release. It focuses on the following areas:

data/LICENSE.md

@@ -1,6 +1,6 @@
 # License
 
-Copyright 2019-2023 Daniel Azuma and the Toys contributors
+Copyright 2019-2026 Daniel Azuma and the Toys contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -23,12 +23,16 @@ Here's a tutorial to help you get a feel of what Toys can do.
 
 Install the **toys** gem using:
 
-    $ gem install toys
+```
+$ gem install toys
+```
 
 This installs the `toys` executable, along with some built-in tools and
 libraries. You can run the executable immediately:
 
-    $ toys
+```
+$ toys
+```
 
 This displays overall help for Toys. If you have `less` installed, Toys will
 use it to display the help screen. Press `q` to exit.
@@ -36,19 +40,25 @@ use it to display the help screen. Press `q` to exit.
 You may notice that the help screen lists some tools that are pre-installed.
 Let's run one of them:
 
-    $ toys system version
+```
+$ toys system version
+```
 
 The `system version` tool displays the current version of the toys gem.
 
-Toys also provides optional tab completion for bash. To install it, execute the
-following command in your shell, or add it to your bash configuration file
-(e.g. `~/.bashrc`).
+Toys also provides optional tab completion for bash and zsh. To install for
+bash, execute the following command in your shell, or add it to your bash
+configuration file (e.g. `~/.bashrc`).
 
-    $(toys system bash-completion install)
+```
+$(toys system bash-completion install)
+```
 
-Toys does not yet specially implement tab completion for zsh or other shells.
-However, if you are using zsh, installing bash completion using `bashcompinit`
-*mostly* works.
+To install for zsh, execute this or add to your `~/.zshrc`.
+
+```
+$(toys system zsh-completion install)
+```
 
 ### Write your first tool
 
@@ -56,32 +66,42 @@ You can define tools by creating a *Toys file*. Go into any directory, and,
 using your favorite editor, create a new file called `.toys.rb` (note the
 leading period). Copy the following text into the file, and save it:
 
-    tool "greet" do
-      desc "My first tool!"
-      flag :whom, default: "world"
-      def run
-        puts "Hello, #{whom}!"
-      end
-    end
+```ruby
+tool "greet" do
+  desc "My first tool!"
+  flag :whom, default: "world"
+  def run
+    puts "Hello, #{whom}!"
+  end
+end
+```
 
 This defines a tool named "greet". Try running it:
 
-    $ toys greet
+```
+$ toys greet
+```
 
 The tool also recognizes a flag on the command line. Try this:
 
-    $ toys greet --whom=ruby
+```
+$ toys greet --whom=ruby
+```
 
 Toys provides a rich set of features for defining command line arguments and
 flags. It can also validate arguments. Try this:
 
-    $ toys greet --bye
+```
+$ toys greet --bye
+```
 
 Notice that Toys automatically generated a usage summary for your tool. It also
 automatically generates a full help screen, which you can view using the
 `--help` flag:
 
-    $ toys greet --help
+```
+$ toys greet --help
+```
 
 Toys searches up the directory hierarchy for Toys files. So it will find this
 `.toys.rb` if you are located in this directory or any subdirectory. It will
@@ -99,53 +119,59 @@ likely to see in real-world usage. Add the following to your `.toys.rb` file.
 (You don't need to replace the greet tool you just wrote; just add this new
 tool to the end of the file.)
 
-    tool "new-repo" do
-      desc "Create a new git repo"
-
-      optional_arg :name, desc: "Name of the directory to create"
-
-      include :exec, exit_on_nonzero_status: true
-      include :fileutils
-      include :terminal
-
-      def run
-        if name.nil?
-          response = ask "Please enter a directory name: "
-          set :name, response
-        end
-        if File.exist? name
-          puts "Aborting because #{name} already exists", :red, :bold
-          exit 1
-        end
-        logger.info "Creating new repo in directory #{name}..."
-        mkdir name
-        cd name do
-          create_repo
-        end
-        puts "Created repo in #{name}", :green, :bold
-      end
-
-      def create_repo
-        exec "git init"
-        File.write ".gitignore", <<~CONTENT
-          tmp
-          .DS_Store
-        CONTENT
-        # You can add additional files here.
-        exec "git add ."
-        exec "git commit -m 'Initial commit'"
-      end
+```ruby
+tool "new-repo" do
+  desc "Create a new git repo"
+
+  optional_arg :name, desc: "Name of the directory to create"
+
+  include :exec, exit_on_nonzero_status: true
+  include :fileutils
+  include :terminal
+
+  def run
+    if name.nil?
+      response = ask "Please enter a directory name: "
+      set :name, response
+    end
+    if File.exist? name
+      puts "Aborting because #{name} already exists", :red, :bold
+      exit 1
+    end
+    logger.info "Creating new repo in directory #{name}..."
+    mkdir name
+    cd name do
+      create_repo
     end
+    puts "Created repo in #{name}", :green, :bold
+  end
+
+  def create_repo
+    exec "git init"
+    File.write ".gitignore", <<~CONTENT
+      tmp
+      .DS_Store
+    CONTENT
+    # You can add additional files here.
+    exec "git add ."
+    exec "git commit -m 'Initial commit'"
+  end
+end
+```
 
 Now you should have an additional tool called `new-repo` available. Type:
 
-    $ toys
+```
+$ toys
+```
 
 The help screen lists both the `greet` tool we started with, and the new
 `new-repo` tool. This new tool creates a directory containing a newly created
 git repo. (It assumes you have `git` available on your path.) Try running it:
 
-    $ toys new-repo foo
+```
+$ toys new-repo foo
+```
 
 That should create a directory `foo`, initialize a git repository within it,
 and make a commit.
@@ -155,7 +181,9 @@ any combination of flags and required and optional arguments. This tool's
 argument is declared with a description string, which you can see if you view
 the tool's help:
 
-    $ toys new-repo --help
+```
+$ toys new-repo --help
+```
 
 The argument is marked as "optional" which means you can omit it. Notice that
 the tool's code detects that it has been omitted and responds by prompting you
@@ -172,7 +200,7 @@ than modules. These symbols are the names of some of Toys's built-in helper
 *mixins*, which are configurable modules that enhance your tool. They may
 provide methods your tool can call, or invoke other behavior. In our example:
 
-*   The `:exec` mixin provides a variety of methods for running external
+ *  The `:exec` mixin provides a variety of methods for running external
     commands. In this example, we use the `exec` method to run shell
     commands, but you can also signal and control these commands, capture
     and redirect streams, and so forth. Note that we pass the
@@ -181,10 +209,10 @@ provide methods your tool can call, or invoke other behavior. In our example:
     to `set -e` in bash). This is a common pattern when writing tools that
     invoke external commands. (If you want more control, the `:exec` mixin also
     provides ways to respond to result codes individually.)
-*   The `:fileutils` mixin provides the methods of the Ruby `FileUtils`
+ *  The `:fileutils` mixin provides the methods of the Ruby `FileUtils`
     library, such as `mkdir` and `cd` used in this example. It's effectively
     shorthand for `require "fileutils"; include ::FileUtils`.
-*   The `:terminal` mixin provides styled output, as you can see with the style
+ *  The `:terminal` mixin provides styled output, as you can see with the style
     codes being passed to `puts`. It also provides some user interaction
     commands such as `ask`, as well as spinners and other controls. You can see
     operation of the `:terminal` mixin in the tool's output, which is styled
@@ -193,7 +221,9 @@ provide methods your tool can call, or invoke other behavior. In our example:
 
 Now try running this:
 
-    $ toys new-repo bar --verbose
+```
+$ toys new-repo bar --verbose
+```
 
 You'll notice some diagnostic log output. Toys provides a standard Ruby Logger
 for each tool, and you can use it to emit diagnostic logs directly as
@@ -219,14 +249,18 @@ If you have a project with a Rakefile, move into that directory and create a
 new file called `.toys.rb` in that same directory (next to the Rakefile). Add
 the following line to your `.toys.rb` file:
 
-    expand :rake
+```ruby
+expand :rake
+```
 
 This syntax is called a "template expansion." It's a way to generate tools
 programmatically. In this case, Toys provides the `:rake` template, which reads
 your Rakefile and generates Toys tools corresponding to all your Rake tasks!
 Now if you run:
 
-    $ toys
+```
+$ toys
+```
 
 You'll see that you now have tools associated with each of your Rake tasks. So
 if you have a `rake test` task, you can run it using `toys test`.
@@ -326,7 +360,7 @@ because it has a few known bugs that affect Toys.
 
 ## License
 
-Copyright 2019-2025 Daniel Azuma and the Toys contributors
+Copyright 2019-2026 Daniel Azuma and the Toys contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/builtins/do.rb

@@ -15,7 +15,18 @@ long_desc \
   "You may change the delimiter using the --delim flag. For example:",
   ["    toys do --delim=/ rails build --staging / deploy --migrate"],
   "The --delim flag must appear first before the tools to run. Any flags that appear later in" \
-    " the command line will be passed to the tools themselves."
+    " the command line will be passed to the tools themselves.",
+  "",
+  "You may also make additional tools available to the tools you run, by passing the --gem," \
+    " --git, and --path flags. Each adds a source of tools, which takes priority over the" \
+    " tools that would otherwise be found. The three flags may be repeated and interleaved," \
+    " and the source added by the leftmost flag takes priority over the sources added by the" \
+    " flags to its right. For example:",
+  ["    toys do --gem=my-tools --git=https://github.com/dazuma/example deploy --migrate"],
+  "Here, a tool defined by both sources is taken from the gem. See the descriptions of the" \
+    " individual flags below for the syntax of their values. Note that the commas within those" \
+    " values are part of the flag value, and are unrelated to the delimiter that separates the" \
+    " tools to run."
 
 flag :delim do
   flags "-d", "--delim=VALUE"
@@ -24,6 +35,67 @@ flag :delim do
   long_desc "Sets the delimiter that separates tool invocations. The default value is \",\"."
 end
 
+# The source flags all share the :sources key, and their handlers append to
+# the same array, tagging each value with the kind of source requested. That
+# way the array records the order in which the flags appeared on the command
+# line, across all of the flags, which is the order that determines priority.
+# The handlers store the raw value; parsing happens later, in build_cli,
+# because an error raised from a handler would come out of the argument parser
+# as a stack trace rather than as a simple message.
+
+flag :sources do
+  flags "--gem=GEM"
+  handler { |val, prev| prev + [[:gem, val]] }
+  default []
+  desc "Make the tools from the given gem available"
+  long_desc \
+    "Adds the tools from the given gem, prompting to install the gem if it is not present.",
+    "",
+    "The value is the gem name, optionally followed by any number of version requirements," \
+      " all separated by commas. Whitespace surrounding each element is ignored. The version" \
+      " requirements use the same syntax as Rubygems and Bundler. For example:",
+    ["    --gem=\"my-tools, ~> 1.5, >= 1.5.2\""]
+end
+
+flag :sources do
+  flags "--git=SPEC"
+  handler { |val, prev| prev + [[:git, val]] }
+  default []
+  desc "Make the tools from the given git repository available"
+  long_desc \
+    "Adds the tools from the given git repository, fetching the repository into a local cache" \
+      " if it is not already there.",
+    "",
+    "The value is the git remote (i.e. the repository URL or path), optionally followed by any" \
+      " number of \"key=value\" elements, all separated by commas. Whitespace surrounding each" \
+      " element, and surrounding each equals sign, is ignored. For example:",
+    ["    --git=\"https://github.com/dazuma/example, path=toys, commit=main\""],
+    "The recognized keys are:",
+    ["    path     The file or directory within the repository to load. By default, the"],
+    ["             entire repository is loaded."],
+    ["    commit   The SHA, tag, or branch to load. By default, the repository head is used."],
+    ["    update   Whether to refresh a previously cached repository. Pass \"true\" or \"false\","],
+    ["             or a number of seconds, to refresh only if the cache is at least that old."],
+    ["             The default is \"false\"."],
+    "Unlike --gem, which takes its elements positionally, the elements here are named, because" \
+      " a git source has three independent optional fields and a positional syntax could not" \
+      " express, for example, a path with no commit.",
+    "",
+    "There is no way to escape a comma appearing within the value."
+end
+
+flag :sources do
+  flags "--path=PATH"
+  handler { |val, prev| prev + [[:path, val]] }
+  default []
+  complete_values :file_system
+  desc "Make the tools from the given path available"
+  long_desc \
+    "Adds the tools from the given file system path. The path must name either a directory" \
+      " of tools, or a single Ruby file defining tools. For example:",
+    ["    --path=/path/to/my-tools"]
+end
+
 remaining_args :commands do
   complete do |context|
     commands = context.arg_parser.data[:commands]
@@ -37,10 +109,144 @@ end
 enforce_flags_before_args
 
 def run
+  tool_cli = build_cli
   commands
     .chunk { |arg| arg == delim ? :_separator : true }
     .each do |_, action|
-      code = cli.run(action)
+      code = tool_cli.run(action)
       exit(code) unless code.zero?
     end
 end
+
+# Returns the CLI used to run the requested tools. Normally this is simply the
+# current CLI, but if any sources were requested, we need a new CLI because
+# sources cannot be added to a CLI that has already started loading tools. The
+# new CLI copies the current sources and adds the requested ones on top of
+# them. The requested sources are added in reverse order so that the first flag
+# on the command line ends up with the highest priority.
+#
+# All the flag values are parsed up front, in command line order, so that a
+# malformed value is reported before any source is added, and is reported
+# against the first offending flag rather than the last.
+#
+# All added sources are then proactively resolved and failures reported.
+def build_cli
+  specs = sources.map { |kind, value| parse_source_request(kind, value) }
+  return cli if specs.empty?
+  require "toys/utils/gems" if specs.any? { |spec| spec.is_a?(::Toys::SourceSpec::Gem) }
+  tool_cli = cli.child(copy_sources: true) do |child_cli|
+    specs.reverse_each { |spec| child_cli.add_source(spec, high_priority: true) }
+  end
+  begin
+    tool_cli.loader.resolve_sources
+  rescue ::Toys::ToolSourceError => e
+    logger.error("Unable to resolve the given tool sources: #{e.message}")
+    exit(1)
+  end
+  tool_cli
+end
+
+# Parses and checks a single source request, returning the source spec to add
+# to the CLI later.
+def parse_source_request(kind, value)
+  case kind
+  when :gem
+    parse_gem_request(value)
+  when :git
+    parse_git_request(value)
+  when :path
+    parse_path_request(value)
+  end
+end
+
+# Splits a --gem flag value into the gem name and its version requirements,
+# and checks that both are valid. The requirements are validated by Rubygems
+# itself, but are passed along as the original strings.
+def parse_gem_request(gem_request)
+  gem_name, *gem_version = gem_request.split(",", -1).map(&:strip)
+  if gem_name.nil? || gem_name.empty? || gem_version.any?(&:empty?)
+    logger.fatal("Invalid --gem value: #{gem_request.inspect}")
+    exit(1)
+  end
+  begin
+    ::Gem::Requirement.create(*gem_version)
+  rescue ::Gem::Requirement::BadRequirementError => e
+    logger.fatal("Invalid version requirement for gem #{gem_name.inspect}: #{e.message}")
+    exit(1)
+  end
+  ::Toys::SourceSpec.gem(gem_name, version: gem_version)
+end
+
+# Splits a --git flag value into the git remote and the options that follow it,
+# and checks that all of them are valid. Unrecognized and duplicate keys are
+# errors rather than being ignored or resolved as last-wins, because a mistyped
+# key would otherwise silently load something other than what was asked for.
+def parse_git_request(git_request)
+  git_remote, *elements = git_request.split(",", -1).map(&:strip)
+  git_error(git_request, "the git remote is required") if git_remote.nil? || git_remote.empty?
+  opts = { path: nil, commit: nil, update: false }
+  seen_keys = []
+  elements.each do |element|
+    key, value = parse_git_element(git_request, element, seen_keys)
+    case key
+    when "path"
+      opts[:path] = value
+    when "commit"
+      opts[:commit] = value
+    when "update"
+      opts[:update] = parse_git_update(git_request, value)
+    else
+      git_error(git_request, "unrecognized key #{key.inspect}")
+    end
+  end
+  ::Toys::SourceSpec.git(git_remote, **opts)
+end
+
+# Splits one element following the git remote into its key and value, and
+# checks that it is well-formed and does not repeat an earlier key.
+def parse_git_element(git_request, element, seen_keys)
+  key, value = element.split("=", 2).map(&:strip)
+  if value.nil? || key.empty?
+    git_error(git_request, "expected \"key=value\" but got #{element.inspect}")
+  end
+  git_error(git_request, "empty value for key #{key.inspect}") if value.empty?
+  git_error(git_request, "duplicate key #{key.inspect}") if seen_keys.include?(key)
+  seen_keys << key
+  [key, value]
+end
+
+# Interprets the value of the "update" key in a --git flag value, which is
+# either a boolean or a number of seconds.
+def parse_git_update(git_request, value)
+  case value
+  when "true"
+    true
+  when "false"
+    false
+  when /\A\d+\z/
+    value.to_i
+  else
+    git_error(git_request, "invalid update value #{value.inspect}")
+  end
+end
+
+# Reports a malformed --git flag value, naming the part of the value that was
+# not understood.
+def git_error(git_request, message)
+  logger.fatal("Invalid --git value: #{git_request.inspect}: #{message}")
+  exit(1)
+end
+
+# Checks that a --path flag value is present. Whether the path actually names
+# tools is left to the loader to determine, so that this tool does not have to
+# duplicate that rule. The spec carries no context directory, like the gem and
+# git sources, because it is injected from the command line rather than found
+# in a project.
+def parse_path_request(path_request)
+  path = path_request.strip
+  if path.empty?
+    logger.fatal("Invalid --path value: #{path_request.inspect}")
+    exit(1)
+  end
+  ::Toys::SourceSpec.path(path)
+end