CLI command to get Clarity documentation

[hugo-stacks]

AI coding agents don't know Clarity well.
They are not specifically trained for it, and there's low training data.

I've seen agents struggling with Clarity 4 at-block? especially.

They can check the online docs, but also, Clarinet already contains the whole Clarity language reference here (from the core repo).

This doc can be read in the LSP or in the clarinet console with

::functions                             Display all the native functions available in clarity
::keywords                              Display all the native keywords available in clarity
::describe <function> | <keyword>       Display documentation for a given native function or keyword

But this isn't really helpful to a coding agent.

Hypothese

Would it actually help AI agents if they could easily access the Clarity language reference from the CLI?

Idea

Something like:

$ clarinet doc ls functions # (or functions ls)
$ clarinet doc ls keyword
$ clarinet doc describe <function|keyword>

clarinet doc ls should only show the functions and keywords of the current Clarity version (clarinet_defaults::DEFAULT_CLARITY_VERSION), otherwise, it shows functions or keywords that are not valid anymore (can be super confusing for as-contract? vs as-contract).
It could accept a --clarity-version=<v> argument.
It should clearly state that it's "showing functions for Clarity "

[linear]

CNET-217

[jbencin-stacks]

Maybe an easier way to approach this is to allow running a single clarinet console expression on directly from the command line:

clarinet eval "::functions"
clarinet eval "(+ u1 u2)"

This would instantly get you everything available in clarinet console, and would have the added benefit of allowing LLMs to quickly test Clarity snippets. Actually, Claude specifically requested this feature when I asked what features it wanted in the Clarinet binary

[hugo-stacks]

Having clarinet eval "<clarity epxression> would definitely be super helpful, we should do it.

I have some doubts regarding UX of clarinet eval "::functions".
::functions ::keywords and ::describe currently live in the console/REPL, but maybe that was a mistake, that doesn't seem very intuitive to use, and since it's doesn't actually interact with the session, I'm not sure the belongs there.

From technical point of view, the clarinet console does quite a lot of things in the backgrounds. Checks for a Clarinet.toml, for a deployment.plan, starts a session, set up contracts and genesis accounts, etc. I think that's useless in the context of showing documentation, that doesn't require all that.

Also, a dedicated clarinet doc command would benefit from all the CLI self documentation / discovery (with clap), it would show up in clarinet --help and have it's own clarinet doc --help, clarinet doc functions --help. While the console would mean using it's dedicated ::help` command, that is way less powerful.

In short, I think clarinet doc could be dead simple, while clarinet eval|console imply some more complex code paths. But ultimately, they would share some logic / content.

---

Regardless of how it's implemented, I also think that it would be nice if ::function and ::keyword would also accept a clarity version argument, and clearly inform the user what version it's showing right now. Because I think that it's pretty useless to a human/ai right now since it's not showing for instance that as-contract doesn't exist in Clarity 4, and has be replaced with the more complex as-contract?