feat!: consolidate cot cli commands into one by ElijahAhianyo · Pull Request #587 · cot-rs/cot

ElijahAhianyo · 2026-06-10T23:45:50Z

Background

cot currently exposes CLI commands through two separate entry points:

cot-cli crate (cot <command>): handles project scaffolding, migration listing, migration generation, and shell completions.
Compiled binary (invoked directly): exposes runtime commands such as check, running migrations (which is also triggered implicitly at startup), and any custom user-defined task commands.

In addition, running and building a cot app relies on Cargo tooling. In summary, there are three ways to invoke CLI commands today:

cot <command> via the cot-cli crate
Invoking the compiled binary directly for commands not available in cot-cli
Using Cargo to build and run apps

This PR focuses on unifying 1 and 2 for ergonomics: cot now acts as the single entry point for all commands, proxying any unrecognized command to the compiled binary if it exists there. Option 3 (Cargo invocation) is out of scope for this PR and can be revisited in a follow-up if proxying those commands makes sense.

Approach

When cot receives a command it does not recognize, it resolves the target binary (target/debug by default, or target/release if --release is passed), queries it for its available commands via a metadata flag, and either forwards the command along with all provided arguments or returns an error if the command is not found in the binary either.

Metadata

To support proxying, the cot crate exposes a --metadata flag. At runtime, the binary uses reflection to enumerate all registered CLI commands and prints them as JSON to stdout. This serves two purposes: it tells cot-cli whether a given command should be forwarded, and it provides the information needed to render accurate help text.

Example:

$ ./target/debug/forms --metadata
{
  "binary_name": "forms",
  "commands": [
    {
      "name": "check",
      "about": "Verifies the configuration, including connections to the database and other services",
      "aliases": [],
      "subcommands": []
    },
    {
      "name": "collect-static",
      "about": "Collects all static files into a static directory",
      "aliases": [],
      "subcommands": []
    }
  ]
}

Caching

Querying the binary on every invocation would be wasteful, so the metadata response is cached in .cot/command-cache.json. The cache stores the binary's modified time (mtime) alongside the metadata and is invalidated automatically whenever the binary is rebuilt.

Workspaces

When working inside a Cargo workspace, a --package (-p) flag must be provided to specify which package's binary should be targeted.

Type of change

github-actions · 2026-06-10T23:50:05Z

Bencher Report

Project	cot
Branch	elijah/cot-proxy-cmd
Testbed	github-ubuntu-latest

Click to view all benchmark results

Benchmark	Latency	Benchmark Result microseconds (µs) (Result Δ%)	Upper Boundary microseconds (µs) (Limit %)
empty_router/empty_router	📈 view plot 🚷 view threshold	13,652.00 µs (+59.40%) Baseline: 8,564.87 µs	16,300.96 µs (83.75%)
json_api/json_api	📈 view plot 🚷 view threshold	1,054.90 µs (+0.33%) Baseline: 1,051.42 µs	1,373.79 µs (76.79%)
nested_routers/nested_routers	📈 view plot 🚷 view threshold	989.43 µs (+0.62%) Baseline: 983.37 µs	1,257.69 µs (78.67%)
single_root_route/single_root_route	📈 view plot 🚷 view threshold	954.81 µs (+0.85%) Baseline: 946.79 µs	1,219.97 µs (78.27%)
single_root_route_burst/single_root_route_burst	📈 view plot 🚷 view threshold	17,185.00 µs (+0.53%) Baseline: 17,094.45 µs	21,564.70 µs (79.69%)

🐰 View full continuous benchmarking report in Bencher

- help for workspaces and packages now dispatch to the custom help handler

codecov · 2026-06-23T17:50:53Z

Codecov Report

❌ Patch coverage is 87.56331% with 221 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
cot-cli/src/test_harness.rs	66.16%	119 Missing and 17 partials ⚠️
cot-cli/src/project.rs	89.91%	43 Missing and 14 partials ⚠️
cot-cli/src/main.rs	87.67%	15 Missing and 3 partials ⚠️
cot/src/project.rs	0.00%	5 Missing ⚠️
cot/src/cli.rs	0.00%	3 Missing ⚠️
cot-cli/src/handlers.rs	99.56%	0 Missing and 2 partials ⚠️

Flag	Coverage Δ
rust	`90.05% <87.56%> (-0.17%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
cot-cli/src/args.rs	`100.00% <100.00%> (ø)`
cot-cli/src/utils.rs	`96.14% <100.00%> (+2.13%)`	⬆️
cot/src/metadata.rs	`100.00% <100.00%> (ø)`
cot-cli/src/handlers.rs	`98.79% <99.56%> (+2.86%)`	⬆️
cot/src/cli.rs	`86.49% <0.00%> (-0.85%)`	⬇️
cot/src/project.rs	`88.21% <0.00%> (-0.56%)`	⬇️
cot-cli/src/main.rs	`88.95% <87.67%> (-11.05%)`	⬇️
cot-cli/src/project.rs	`89.91% <89.91%> (ø)`
cot-cli/src/test_harness.rs	`66.16% <66.16%> (ø)`

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

m4tx · 2026-07-29T12:21:45Z

+    #[cfg(unix)]
+    {
+        let err = std::process::Command::new(&proj.path).args(args).exec();
+        anyhow::bail!("Failed to exec {}: {err}", proj.path.display());
+    }
+
+    #[cfg(not(unix))]
+    {
+        let status = std::process::Command::new(&proj.path).args(args).status()?;
+        std::process::exit(status.code().unwrap_or(1));
+    }


Where's the difference between Unix-like and non-Unix-like platforms coming from? Why do we need separate code paths here?

The idea here is to replace the cot process with that of the child(the binary) whenever we forward to(or run) the binary. The exec call is only available on POSIX. Windows doesn't provide a way to do this, so we just spawn the child and block until it exits. Left a comment to outline this behavior as well.
On a side note, one issue i think isnt being handled is signal forwarding in the non-Unix case

m4tx · 2026-07-29T12:24:39Z

Do we need all this machinery here? Any chance that running cargo run would suffice instead?

…h/cot-proxy-cmd

…h/cot-proxy-cmd # Conflicts: # cot-cli/tests/snapshot_testing/external/check.rs

m4tx

Oof, this is a big change! One big major possible improvement I still see is whether we could offload some of the logic (especially in the cot-cli crate) to some existing crates, or cargo itself. (see the comments) Let me know what you think!

m4tx · 2026-08-18T16:47:05Z

+/// argv, before clap has parsed anything. Needed because `project::load`
+/// must run before `Cli::parse` for the `--help` interception path.
+#[must_use]
+pub fn extract_package_arg(raw: &[String]) -> Option<String> {


Should we also handle cases like cot check -- -p package here? (and if so, we should have tests for these as well)

This function is only called in main() after we split on -- to differentiate internal args from args forwarded to the binary. In practice, it wouldn't receive raw args, but I've added a defensive check to the function to handle that case.

Also, shouldn't this be cot check -p package instead of cot check -- -p package? I'd imagine that external args (args after the -- delimiter) are forwarded to the binary, so we should expect this to throw an error.

That also brings me to this scenario: commands like migration rollback, collect-static, and check live in the binary and are treated as external commands from the perspective of cot-cli, just like custom commands. However, we market these commands as first-class cot-cli commands to end users. So users would expect all cot commands to follow the same convention, with args coming before the delimiter, rather than having to figure out which internal commands require args after the delimiter and which require args before.

I think as a follow-up to this PR, we should have some mechanism to make cot-cli aware of what commands to treat as first-class citizens, and also maybe a way to make CliTask aware of flags already registered by cot-cli (like --package and --release).

What do you think?

m4tx · 2026-08-18T18:04:08Z

+        .context("Cargo.toml has no [package] section and no [[bin]] targets")
+}
+
+fn resolve_target_dir(start_dir: &Path) -> PathBuf {


What if the target dir is set in ~/.cargo/config.toml? Will it also work?

This should be handled by cargo-metadata since it delegates that discovery to the cargo toolchain

m4tx · 2026-08-18T18:09:30Z

@@ -0,0 +1,946 @@
+use std::fmt::Write;


Another issue I have with this file is that it duplicates a lot of logic with cargo itself. This seems very brittle, and sounds like we could be missing some edge cases our users could run into (e.g. see my comment about resolving the target directory).

I'm wondering if all of that is really needed? I'm thinking whether we could:

Use cargo itself for some of that, e.g. by using cargo build --mesage-format json

Use a specialised crate for this, e.g. cargo_toml

Yeah, the main motivation for moving away from cargo run on every run is that on a hot path where no recompile of the binary is needed, cargo still walks up the dependency graph to find fresh/dirty deps that need to be recompiled, which isn't free (time-wise). This isn't a problem for smaller projects, but I'm concerned it can give a bad user experience for larger projects. I figured using cargo build as the last resort (the cold path where the binary isn't compiled at all) would a much better experience.
I also agree on the brittle approach of manually obtaining the target directory/binary. I looked into the cargo_metadata crate, which seems to obtain the outputs of cargo metadata and cargo --message-format=json and correctly resolves the target dir and handles the case where CARGO_TARGET_DIR is set (which cargo_toml crate falls short of). It's also less expensive compared to cargo build when you run with the --no-deps flag. One thing about cargo_metadata to note is that it gets you the information about the target dir and available binaries, which is one part of the job done. However, it leaves it up to you to identify which binary or handle any disambiguations if there are multiple binaries.

Overall, the flow I had in mind looks like this:

Try to find the path to the binary by getting this info from cargo_metadata
a. If the binary exists, try to obtain metadata information from the cache(hot path) if it exists and binary hasnt been recompiled or from the binary itself(warm path) using the --cot-internal-cli-metadata flag
b. If the binary does not exist(cold path), build the binary at request of the user using cargo build via the build flag(I'm wondering if this should be implicit and automatic). Then go ahead to obtain metadata information like in step a

After obtaining the metadata, invoke the binary and forward any args to it.

The help command follows the same approach; it tries to check if the binary exists and tries to obtain metadata. If it doesn't exist or metadata extraction fails, it warns the user and falls back to the generic help command by clap, which shows only commands defined in the cot-cli

What do you think of this?

consolidate cot cli commands into one

fc8f8f1

github-actions Bot added A-deps Area: Dependencies C-cli Crate: cot-cli (issues and Pull Requests related to Cot CLI) C-lib Crate: cot (main library crate) labels Jun 10, 2026

ElijahAhianyo changed the title ~~consolidate cot cli commands into one~~ feat!: consolidate cot cli commands into one Jun 10, 2026

ElijahAhianyo added 9 commits June 11, 2026 00:16

remove dead code

683b2a6

- improve error messages.

8a0c6b8

- help for workspaces and packages now dispatch to the custom help handler

Merge branch 'master' into elijah/cot-proxy-cmd

2a4bfba

unit tests initial

d73cd10

Merge branch 'master' into elijah/cot-proxy-cmd

219d898

some minor refactor

0cfd155

fix clippy

9beb8ea

fix the snapshot tests

48353cb

gate unix::process::CommandExt behind unix flag

00016d3

ElijahAhianyo marked this pull request as ready for review June 23, 2026 16:41

ElijahAhianyo and others added 2 commits June 23, 2026 17:04

fix exec error on windows

7f85e45

chore(pre-commit.ci): auto fixes from pre-commit hooks

86cfd37

ElijahAhianyo added 2 commits June 23, 2026 19:05

make serde_json a required dep

9c9b467

comment improve

4e7b5d6

ElijahAhianyo requested review from m4tx and seqre June 25, 2026 11:53

Merge branch 'master' into elijah/cot-proxy-cmd

ea45e71

ElijahAhianyo mentioned this pull request Jul 17, 2026

feat!: support for rolling back migrations #583

Merged

6 tasks

ElijahAhianyo added 3 commits July 21, 2026 16:12

Merge branch 'master' into elijah/cot-proxy-cmd

464b3c0

update lock files

8001727

update snapshots

0412722

m4tx requested changes Jul 29, 2026

View reviewed changes

ElijahAhianyo mentioned this pull request Jul 30, 2026

docs: Add Migration docs #622

Open

6 tasks

ElijahAhianyo and others added 19 commits August 12, 2026 19:52

rename project harness for consistency

ca25425

fix ui tests

56ddeff

fix dependency mess(hopefully)

3d9ad2f

normalize path separator dor windows

9336b24

fix docstring. Temporarily revert request ui tests to see if CI passes

8387bc9

chore(pre-commit.ci): auto fixes from pre-commit hooks

5bfe9fd

adding some debug statements to instrument windows CI failure

ac5f8bc

Merge remote-tracking branch 'origin/elijah/cot-proxy-cmd' into elija…

5e7f46f

…h/cot-proxy-cmd

chore(pre-commit.ci): auto fixes from pre-commit hooks

abe2318

should compile now

6acd271

Merge remote-tracking branch 'origin/elijah/cot-proxy-cmd' into elija…

f6fcd3d

…h/cot-proxy-cmd

isolating tests

ffe7e72

see if windows test gets fixed

6590dc1

try to build if bin not found

3669369

chore(pre-commit.ci): auto fixes from pre-commit hooks

d51c000

use status so child forwards to parent on windows. see if it works

5a6f0f2

Merge remote-tracking branch 'origin/elijah/cot-proxy-cmd' into elija…

e0cc344

…h/cot-proxy-cmd # Conflicts: # cot-cli/tests/snapshot_testing/external/check.rs

fix miri tests. Also a couple of improvements

afc507e

fix docs test

d2a8549

ElijahAhianyo requested a review from m4tx August 18, 2026 02:18

m4tx requested changes Aug 18, 2026

View reviewed changes

ElijahAhianyo added 8 commits August 20, 2026 20:42

address roughly 85% of comments

43d79ce

Merge branch 'master' into elijah/cot-proxy-cmd

12c56a2

address 2 more comments

7716b12

add some tests to handle target-dir discovery

73ae4ef

normalize path in windows to fix tests

d8dcb36

fix flaky tests

edea1c3

fix help tests

b32dc83

miri ignore

a98e8e8

ElijahAhianyo requested a review from m4tx August 21, 2026 23:41

Uh oh!

Uh oh!

Conversation

ElijahAhianyo commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Approach

Metadata

Caching

Workspaces

Type of change

Uh oh!

github-actions Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

m4tx left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ElijahAhianyo Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ElijahAhianyo Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ElijahAhianyo commented Jun 10, 2026 •

edited

Loading

github-actions Bot commented Jun 10, 2026 •

edited

Loading

codecov Bot commented Jun 23, 2026 •

edited

Loading

ElijahAhianyo Aug 21, 2026 •

edited

Loading

ElijahAhianyo Aug 20, 2026 •

edited

Loading