1use std::env::current_dir;
7
8use clap::{Args, Parser, Subcommand};
9
10#[derive(Debug, Parser)]
12#[command(
13 name = "ask",
14 version,
15 about = "Agent Skills Kit - Download version-specific library docs for AI coding agents",
16 propagate_version = true
17)]
18pub struct Cli {
19 #[command(subcommand)]
20 pub command: Command,
21}
22
23#[derive(Debug, Subcommand)]
24pub enum Command {
25 Install,
27
28 Add(AddArgs),
30
31 Remove(RemoveArgs),
33
34 List(ListArgs),
36
37 Src(SrcArgs),
39
40 Docs(DocsArgs),
42
43 Fetch(FetchArgs),
45
46 Search(SearchArgs),
48
49 Skills(SkillsArgs),
51
52 Cache(CacheArgs),
54}
55
56#[derive(Debug, Args)]
57pub struct AddArgs {
58 pub spec: Option<String>,
61 #[arg(long = "docs-paths")]
63 pub docs_paths: Option<String>,
64 #[arg(long = "clear-docs-paths")]
66 pub clear_docs_paths: bool,
67}
68
69#[derive(Debug, Args)]
70pub struct RemoveArgs {
71 pub name: String,
73}
74
75#[derive(Debug, Args)]
76pub struct ListArgs {
77 #[arg(long)]
79 pub json: bool,
80}
81
82#[derive(Debug, Args)]
83pub struct SrcArgs {
84 pub spec: String,
86 #[arg(long = "no-fetch")]
88 pub no_fetch: bool,
89 #[arg(long)]
91 pub json: bool,
92}
93
94#[derive(Debug, Args)]
95pub struct DocsArgs {
96 pub spec: String,
98 #[arg(long = "no-fetch")]
100 pub no_fetch: bool,
101 #[arg(long)]
103 pub json: bool,
104}
105
106#[derive(Debug, Args)]
107pub struct FetchArgs {
108 #[arg(required = true)]
110 pub specs: Vec<String>,
111 #[arg(short = 'q', long)]
113 pub quiet: bool,
114}
115
116#[derive(Debug, Args)]
117pub struct SearchArgs {
118 pub spec: String,
120 pub query: String,
122 #[arg(long)]
124 pub content: Option<String>,
125 #[arg(long = "top-k")]
127 pub top_k: Option<String>,
128 #[arg(long = "no-fetch")]
130 pub no_fetch: bool,
131}
132
133#[derive(Debug, Args)]
134pub struct SkillsArgs {
135 #[command(subcommand)]
136 pub command: Option<SkillsCommand>,
137 #[arg(value_name = "SPEC")]
139 pub spec: Option<String>,
140 #[arg(long = "no-fetch")]
142 pub no_fetch: bool,
143}
144
145#[derive(Debug, Subcommand)]
146pub enum SkillsCommand {
147 List(SkillsListArgs),
149 Install(SkillsInstallArgs),
151 Remove(SkillsRemoveArgs),
153}
154
155#[derive(Debug, Args)]
156pub struct SkillsListArgs {
157 pub spec: String,
159 #[arg(long = "no-fetch")]
161 pub no_fetch: bool,
162}
163
164#[derive(Debug, Args)]
165pub struct SkillsInstallArgs {
166 pub spec: String,
168 #[arg(long = "no-fetch")]
170 pub no_fetch: bool,
171 #[arg(long)]
173 pub force: bool,
174 #[arg(long)]
176 pub agent: Option<String>,
177}
178
179#[derive(Debug, Args)]
180pub struct SkillsRemoveArgs {
181 pub spec: String,
183 #[arg(long = "ignore-missing")]
185 pub ignore_missing: bool,
186}
187
188#[derive(Debug, Args)]
189pub struct CacheArgs {
190 #[command(subcommand)]
191 pub command: CacheCommand,
192}
193
194#[derive(Debug, Subcommand)]
195pub enum CacheCommand {
196 Ls(CacheLsArgs),
198 Gc(CacheGcArgs),
200 Clean(CacheCleanArgs),
202}
203
204#[derive(Debug, Args)]
205pub struct CacheLsArgs {
206 #[arg(long)]
208 pub kind: Option<String>,
209 #[arg(long)]
211 pub json: bool,
212}
213
214#[derive(Debug, Args)]
215pub struct CacheGcArgs {
216 #[arg(long = "dry-run")]
218 pub dry_run: bool,
219 #[arg(long = "older-than")]
221 pub older_than: Option<String>,
222 #[arg(long)]
224 pub json: bool,
225}
226
227#[derive(Debug, Args)]
228pub struct CacheCleanArgs {
229 #[arg(long)]
231 pub legacy: bool,
232}
233
234pub fn run(cli: Cli) -> anyhow::Result<()> {
236 match cli.command {
237 Command::Install => {
238 crate::install::run_install(¤t_dir()?, &Default::default())?;
239 Ok(())
240 }
241 Command::List(args) => run_list(args),
242 Command::Add(args) => run_add_cmd(args),
243 Command::Remove(args) => run_remove_cmd(args),
244 Command::Src(args) => run_src_cmd(args),
245 Command::Docs(args) => run_docs_cmd(args),
246 Command::Fetch(args) => run_fetch_cmd(args),
247 Command::Search(args) => run_search_cmd(args),
248 Command::Skills(args) => run_skills_cmd(args),
249 Command::Cache(args) => run_cache_cmd(args),
250 }
251}
252
253fn run_add_cmd(args: AddArgs) -> anyhow::Result<()> {
257 let client = crate::http::UreqClient::new();
258 let project_dir = current_dir()?;
259
260 let Some(spec) = args.spec else {
261 use crate::commands::add::{run_interactive_add, RunInteractiveDeps};
262 let report = run_interactive_add(&client, &project_dir, &RunInteractiveDeps::default())?;
263 for line in &report.stdout {
264 println!("{line}");
265 }
266 for line in &report.stderr {
267 eprintln!("{line}");
268 }
269 if report.exit_code != 0 {
270 std::process::exit(report.exit_code);
271 }
272 return Ok(());
273 };
274
275 use crate::commands::add::{run_add, RunAddDeps, RunAddOptions};
276 let options = RunAddOptions {
277 project_dir,
278 spec,
279 docs_paths_arg: args.docs_paths,
280 clear_docs_paths: args.clear_docs_paths,
281 };
282 match run_add(&client, &options, &RunAddDeps::default()) {
283 Ok(report) => {
284 for line in &report.stdout {
285 println!("{line}");
286 }
287 for line in &report.stderr {
288 eprintln!("{line}");
289 }
290 Ok(())
291 }
292 Err(err) => {
293 eprintln!("{err}");
294 std::process::exit(1);
295 }
296 }
297}
298
299fn run_skills_cmd(args: SkillsArgs) -> anyhow::Result<()> {
302 use crate::commands::skills::{
303 run_skills_install, run_skills_list, run_skills_remove, RunSkillsInstallOptions,
304 RunSkillsListOptions, RunSkillsRemoveOptions, SkillsReport,
305 };
306 let client = crate::http::UreqClient::new();
307 let project_dir = current_dir()?;
308
309 let report: SkillsReport = match args.command {
310 None => {
311 let Some(spec) = args.spec else {
313 return Ok(());
314 };
315 run_skills_list(
316 &client,
317 &RunSkillsListOptions {
318 spec,
319 project_dir,
320 no_fetch: args.no_fetch,
321 },
322 &Default::default(),
323 )
324 }
325 Some(SkillsCommand::List(a)) => run_skills_list(
326 &client,
327 &RunSkillsListOptions {
328 spec: a.spec,
329 project_dir,
330 no_fetch: a.no_fetch,
331 },
332 &Default::default(),
333 ),
334 Some(SkillsCommand::Install(a)) => {
335 let agents = a.agent.as_deref().and_then(|s| {
336 let v: Vec<String> = s
337 .split(',')
338 .map(|x| x.trim().to_string())
339 .filter(|x| !x.is_empty())
340 .collect();
341 (!v.is_empty()).then_some(v)
342 });
343 run_skills_install(
344 &client,
345 &RunSkillsInstallOptions {
346 spec: a.spec,
347 project_dir,
348 no_fetch: a.no_fetch,
349 force: a.force,
350 agents,
351 },
352 &Default::default(),
353 )?
354 }
355 Some(SkillsCommand::Remove(a)) => run_skills_remove(&RunSkillsRemoveOptions {
356 spec: a.spec,
357 project_dir,
358 ignore_missing: a.ignore_missing,
359 })?,
360 };
361
362 for line in &report.stdout {
363 println!("{line}");
364 }
365 for line in &report.stderr {
366 eprintln!("{line}");
367 }
368 if report.exit_code != 0 {
369 std::process::exit(report.exit_code);
370 }
371 Ok(())
372}
373
374fn run_src_cmd(args: SrcArgs) -> anyhow::Result<()> {
378 use crate::commands::src::{run_src, RunSrcOptions};
379 let client = crate::http::UreqClient::new();
380 let options = RunSrcOptions {
381 spec: args.spec,
382 project_dir: current_dir()?,
383 no_fetch: args.no_fetch,
384 json: args.json,
385 };
386 match run_src(&client, &options) {
387 Ok(out) => {
388 println!("{out}");
389 Ok(())
390 }
391 Err(err) => {
392 eprintln!("{err}");
393 std::process::exit(1);
394 }
395 }
396}
397
398fn run_fetch_cmd(args: FetchArgs) -> anyhow::Result<()> {
401 use crate::commands::fetch::{run_fetch, RunFetchOptions};
402 let client = crate::http::UreqClient::new();
403 let options = RunFetchOptions {
404 specs: args.specs,
405 project_dir: current_dir()?,
406 quiet: args.quiet,
407 };
408 let report = run_fetch(&client, &options);
409 for line in &report.stdout {
410 println!("{line}");
411 }
412 for line in &report.stderr {
413 eprintln!("{line}");
414 }
415 if report.had_errors {
416 std::process::exit(1);
417 }
418 Ok(())
419}
420
421fn run_cache_cmd(args: CacheArgs) -> anyhow::Result<()> {
423 use crate::store::cache::{
424 build_cache_gc_model, build_cache_ls_model, cache_clean_legacy, cache_gc, cache_ls,
425 detect_legacy_layout, format_bytes, parse_duration, CacheGcOptions, CacheKind,
426 };
427 use crate::store::resolve_ask_home;
428
429 let ask_home = resolve_ask_home();
430
431 match args.command {
432 CacheCommand::Ls(a) => {
433 let filter = match a.kind.as_deref() {
434 Some(k) => match CacheKind::parse(k) {
435 Some(kind) => Some(kind),
436 None => {
437 eprintln!(
438 "Invalid --kind '{k}'. Must be one of: npm, github, web, llms-txt"
439 );
440 std::process::exit(1);
441 }
442 },
443 None => None,
444 };
445 if a.json {
446 let model = build_cache_ls_model(&ask_home, filter);
447 println!("{}", serde_json::to_string_pretty(&model)?);
448 return Ok(());
449 }
450 let entries = cache_ls(&ask_home, filter);
451 if entries.is_empty() {
452 eprintln!("No entries in store at {}", ask_home.display());
453 return Ok(());
454 }
455 eprintln!("Store: {}", ask_home.display());
456 eprintln!(
457 "{} entr{}:\n",
458 entries.len(),
459 if entries.len() == 1 { "y" } else { "ies" }
460 );
461 for e in &entries {
462 println!(
463 " {}/{} {}",
464 e.kind.as_str(),
465 e.key,
466 format_bytes(e.size_bytes)
467 );
468 }
469 let total: u64 = entries.iter().map(|e| e.size_bytes).sum();
470 eprintln!("\nTotal: {}", format_bytes(total));
471 }
472 CacheCommand::Gc(a) => {
473 let scan_roots =
478 std::env::var_os("ASK_GC_SCAN_ROOTS").map(|v| std::env::split_paths(&v).collect());
479 let older_than = match a.older_than.as_deref() {
480 Some(raw) => match parse_duration(raw) {
481 Some(ms) => Some(ms),
482 None => {
483 eprintln!(
484 "Invalid --older-than value '{raw}'. Use format like 30d, 12h, 90m, 60s."
485 );
486 std::process::exit(1);
487 }
488 },
489 None => None,
490 };
491 let opts = CacheGcOptions {
492 dry_run: a.dry_run,
493 scan_roots,
494 older_than,
495 silent: a.json,
496 };
497 if a.json {
498 let model = build_cache_gc_model(&ask_home, &opts);
499 println!("{}", serde_json::to_string_pretty(&model)?);
500 return Ok(());
501 }
502 let result = cache_gc(&ask_home, &opts);
503 if result.removed.is_empty() {
504 eprintln!("Store is clean — no unreferenced entries.");
505 return Ok(());
506 }
507 let n = result.removed.len();
508 let plural = if n == 1 { "y" } else { "ies" };
509 if a.dry_run {
510 eprintln!(
511 "Would remove {n} entr{plural} ({}):",
512 format_bytes(result.freed_bytes)
513 );
514 for e in &result.removed {
515 println!(
516 " {}/{} {}",
517 e.kind.as_str(),
518 e.key,
519 format_bytes(e.size_bytes)
520 );
521 }
522 } else {
523 eprintln!(
524 "Removed {n} entr{plural}, freed {}.",
525 format_bytes(result.freed_bytes)
526 );
527 }
528 }
529 CacheCommand::Clean(a) => {
530 if !a.legacy {
531 eprintln!(
532 "ask cache clean requires a mode. Pass --legacy to remove pre-v2 github store dirs."
533 );
534 std::process::exit(1);
535 }
536 if !detect_legacy_layout(&ask_home) {
537 eprintln!(
538 "No legacy github store detected at {}. Nothing to clean.",
539 ask_home.display()
540 );
541 return Ok(());
542 }
543 let removed = cache_clean_legacy(&ask_home);
544 if removed.is_empty() {
545 eprintln!("No legacy paths removed.");
546 return Ok(());
547 }
548 eprintln!(
549 "Removed {} legacy path{}:",
550 removed.len(),
551 if removed.len() == 1 { "" } else { "s" }
552 );
553 for p in &removed {
554 println!(" {}", p.display());
555 }
556 }
557 }
558 Ok(())
559}
560
561fn run_search_cmd(args: SearchArgs) -> anyhow::Result<()> {
563 use crate::commands::resolve_csp::resolve_csp_default;
564 use crate::commands::search::{run_search, spawn_csp, RunSearchOptions, SearchDeps};
565
566 let content: Vec<String> = args
567 .content
568 .as_deref()
569 .filter(|s| !s.is_empty())
570 .map(|s| {
571 s.split(',')
572 .map(|p| p.trim().to_string())
573 .filter(|p| !p.is_empty())
574 .collect()
575 })
576 .unwrap_or_default();
577 let top_k = match args.top_k.as_deref().filter(|s| !s.is_empty()) {
580 Some(raw) => match raw.parse::<u64>() {
581 Ok(n) => Some(n),
582 Err(_) => {
583 eprintln!("ask: ignoring invalid --top-k '{raw}' (not a number)");
584 None
585 }
586 },
587 None => None,
588 };
589
590 let client = crate::http::UreqClient::new();
591 let deps = SearchDeps {
592 checkout: Default::default(),
593 resolve_csp: &resolve_csp_default,
594 run_csp: &spawn_csp,
595 };
596 let options = RunSearchOptions {
597 spec: args.spec,
598 query: args.query,
599 project_dir: current_dir()?,
600 no_fetch: args.no_fetch,
601 content,
602 top_k,
603 };
604 let report = run_search(&client, &options, &deps);
605 for line in &report.stdout {
606 println!("{line}");
607 }
608 for line in &report.stderr {
609 eprintln!("{line}");
610 }
611 std::process::exit(report.exit_code);
612}
613
614fn run_remove_cmd(args: RemoveArgs) -> anyhow::Result<()> {
616 use crate::commands::remove::{run_remove, RemoveOutcome};
617 match run_remove(¤t_dir()?, &args.name)? {
618 RemoveOutcome::NoAskJson => {
619 eprintln!("No ask.json found — nothing to remove");
620 }
621 RemoveOutcome::NoMatch(target) => {
622 eprintln!("No ask.json entry matches '{target}'");
623 }
624 RemoveOutcome::Removed(spec) => {
625 eprintln!("Removed {spec}");
626 }
627 }
628 Ok(())
629}
630
631fn run_docs_cmd(args: DocsArgs) -> anyhow::Result<()> {
635 use crate::commands::docs::{run_docs, RunDocsOptions};
636 let client = crate::http::UreqClient::new();
637 let options = RunDocsOptions {
638 spec: args.spec,
639 project_dir: current_dir()?,
640 no_fetch: args.no_fetch,
641 json: args.json,
642 };
643 match run_docs(&client, &options) {
644 Ok(run) => {
645 for w in &run.warnings {
646 eprintln!("{w}");
647 }
648 println!("{}", run.stdout);
649 Ok(())
650 }
651 Err(err) => {
652 eprintln!("{err}");
653 std::process::exit(1);
654 }
655 }
656}
657
658fn run_list(args: ListArgs) -> anyhow::Result<()> {
660 let model = crate::list::build_list_model(¤t_dir()?);
661 if args.json {
662 println!("{}", serde_json::to_string_pretty(&model)?);
663 } else {
664 println!("{}", crate::list::format_list(&model));
665 }
666 Ok(())
667}
668
669#[cfg(test)]
670mod tests {
671 use super::*;
672 use clap::CommandFactory;
673
674 #[test]
675 fn cli_definition_is_valid() {
676 Cli::command().debug_assert();
679 }
680
681 #[test]
682 fn version_is_the_crate_version() {
683 assert_eq!(
686 Cli::command().get_version(),
687 Some(env!("CARGO_PKG_VERSION"))
688 );
689 }
690
691 #[test]
692 fn all_top_level_subcommands_are_present() {
693 let cmd = Cli::command();
694 let names: Vec<_> = cmd.get_subcommands().map(|c| c.get_name()).collect();
695 for expected in [
696 "install", "add", "remove", "list", "src", "docs", "fetch", "search", "skills", "cache",
697 ] {
698 assert!(names.contains(&expected), "missing subcommand: {expected}");
699 }
700 }
701
702 #[test]
703 fn parses_representative_invocations() {
704 Cli::try_parse_from(["ask", "install"]).unwrap();
706 Cli::try_parse_from(["ask", "add", "next", "--docs-paths", "docs,readme"]).unwrap();
707 Cli::try_parse_from(["ask", "list", "--json"]).unwrap();
708 Cli::try_parse_from(["ask", "fetch", "npm:next", "github:a/b", "-q"]).unwrap();
709 Cli::try_parse_from(["ask", "cache", "gc", "--dry-run", "--older-than", "30d"]).unwrap();
710 Cli::try_parse_from(["ask", "skills", "list", "react"]).unwrap();
711 Cli::try_parse_from(["ask", "skills", "install", "react", "--agent", "claude"]).unwrap();
712 Cli::try_parse_from(["ask", "skills", "remove", "react", "--ignore-missing"]).unwrap();
713 Cli::try_parse_from(["ask", "skills", "react"]).unwrap();
715 Cli::try_parse_from(["ask", "skills"]).unwrap();
716 }
717}