In the Dart CLI, how do dart run pkg@version and dart install differ when you want to use a command-line tool published on pub.dev?

## Two ways to use someone else's tool Many Dart packages ship **executables**: code in `bin/`, optionally listed under `executables:` in their `pubspec.yaml`. Dart 3.10 and 3.12 added two commands that use them without making the tool a dependency of your project. | | `dart run <pkg>@...` | `dart install <pkg>` | |---|---|---| | Added in | Dart 3.12 | Dart 3.10 | | Purpose | run once, now | keep available on the PATH | | Result | runs the executable with your arguments | self-contained AOT binaries in a bin directory | | Housekeeping | none | `dart installed`, `dart uninstall` | | Replaces | ad-hoc activation | `dart pub global activate` for most uses | ## dart run with a remote package The syntax is `dart run <PACKAGE>[:<EXECUTABLE>]@[<DESCRIPTOR>] [args]`. The **`@` is what marks the package as remote**: - `dart run dhttpd@` - latest stable version from pub.dev, default executable. - `dart run pubviz@^4.0.0` - a version constraint after the `@`. - `dart run 'pubviz@{hosted: https://my_repository.com, version: ^1.0.0}'` - a YAML descriptor for a custom host. - `dart run 'pubviz@{git: https://github.com/...}'` - a git source. - `dart run pkg:tool@` - a named executable other than the default. Dart resolves the package, downloads it if it is not already cached, compiles and runs it. The current project's `pubspec.yaml` is not touched. The dart.dev guide for `dart doc` uses exactly this to preview generated docs: `dart run dhttpd@ --path doc/api`. Without the `@`, `dart run foo` means something different: run the executable of **`foo` as a dependency of the current package**, at the version your lockfile resolves. ## dart install `dart install` installs or upgrades a tool for global use: 1. It resolves the package - from pub.dev by name, from a git URL, or from a local path; the `<package>@<descriptor>` form accepts the same descriptors as `dart run`, and a version constraint can also follow the name. 2. It installs the executables declared in the package's `executables` section, or all `bin/*.dart` entry points if that section is missing. 3. Per the 3.10 release notes, it compiles them into **self-contained native AOT binaries** using `dart build cli`, so they start quickly and do not need the SDK to resolve packages at launch. 4. It places them in a directory it expects on your PATH and, if that directory is missing from PATH, prints the line to add. Installing the same package again **overwrites** it; `--overwrite` additionally allows replacing an executable of the same name that belongs to a different package. ## Choosing - One-off or scripted use, where pinning the version in the command is useful: `dart run pkg@version`. - A tool you type every day: `dart install`. - A tool the **project** depends on, such as a code generator: add it to `dev_dependencies` and use `dart run pkg:exe`, so everyone gets the version in the lockfile. ## Common mistakes - Adding a one-off tool to `dev_dependencies` just to run it once. - Forgetting the `@`, so `dart run` looks for the package among the project's dependencies and fails. - Using a globally installed code generator instead of the project-pinned one, so teammates generate different output.