diff --git a/crates/pm/Cargo.toml b/crates/pm/Cargo.toml
index f5f2ea6b8e..5df3dbee3d 100644
--- a/crates/pm/Cargo.toml
+++ b/crates/pm/Cargo.toml
@@ -12,6 +12,10 @@ categories  = ["command-line-utilities", "development-tools"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
+[lib]
+name = "utoo_pm"
+path = "src/lib.rs"
+
 [[bin]]
 name = "utoo"
 path = "src/main.rs"
diff --git a/crates/pm/src/cli.rs b/crates/pm/src/cli.rs
index 30bc005f46..be4844fc53 100644
--- a/crates/pm/src/cli.rs
+++ b/crates/pm/src/cli.rs
@@ -1,12 +1,12 @@
 //! Clap CLI definitions for the `utoo` binary.
 //!
 //! Pure argument-parsing types and helpers live here; per-command assembly
-//! and execution belong to the owning `cmd::*` module.
+//! and execution belong to the owning `commands::*` module.
 
 use clap::{Parser, Subcommand};
 
-use crate::cmd::install::InstallArgs;
-use crate::cmd::update::UpdateArgs;
+use crate::commands::install::InstallArgs;
+use crate::commands::update::UpdateArgs;
 use crate::constants::cmd::{
     CLEAN_ABOUT, CLEAN_ALIAS, CLEAN_NAME, COMPLETIONS_ABOUT, COMPLETIONS_ALIAS,
     COMPLETIONS_LONG_ABOUT, COMPLETIONS_NAME, CONFIG_ABOUT, CONFIG_ALIAS, CONFIG_NAME, DEPS_ABOUT,
diff --git a/crates/pm/src/cli_entry.rs b/crates/pm/src/cli_entry.rs
new file mode 100644
index 0000000000..84781cb15a
--- /dev/null
+++ b/crates/pm/src/cli_entry.rs
@@ -0,0 +1,642 @@
+use std::{io, process};
+
+use anyhow::{Context, Result};
+use clap::error::ErrorKind as ClapErrorKind;
+use clap::{CommandFactory, FromArgMatches};
+
+use crate::cli::{Cli, Commands, detect_shell_from_env};
+use crate::constants::APP_VERSION;
+use crate::error::{CliError, ErrorKind, classify};
+use crate::helper::auto_update::init_auto_update;
+use crate::helper::self_pin::handoff_if_needed;
+use crate::model::cli_output::{
+    CompletionsResult, ErrorDetails, HelpResult, HelpTarget, InitResult, RequestedPackage,
+    RequiredBy, VersionResult,
+};
+use crate::service::config::ConfigService;
+use crate::service::script::{MissingScript, ScriptExit, script_failure_details};
+use crate::service::workspace::WorkspaceFilter;
+use crate::types::InitOutput;
+use crate::util::cli_enum::{
+    ColorPolicy, ConfigScope, ConfirmationPolicy, ConsoleVerbosity, InitMode, OutputFormat,
+    ProvenancePolicy, ScriptPolicy,
+};
+use crate::util::config_file::Config;
+use crate::util::format_print::{format_resolve_chain, resolve_chain};
+use crate::util::invocation::{self, Invocation};
+use crate::util::logger::{get_log_file_path, init_tracing, log_time, log_time_end};
+use crate::util::presenter;
+use crate::{InitializeOptions, commands};
+
+/// Run the complete `utoo` command-line application.
+///
+/// Embedders normally call the functions under [`crate::commands`] instead.
+/// This entry point exists so the native binary stays a thin wrapper around
+/// the same library crate.
+pub fn run() {
+    invocation::start();
+    crate::util::sysconf::init();
+
+    let worker_threads = std::thread::available_parallelism()
+        .map(|n| n.get())
+        .unwrap_or(4);
+
+    let result = tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .worker_threads(worker_threads)
+        .build()
+        .expect("failed to build tokio runtime")
+        .block_on(async_main());
+
+    if let Err(e) = result {
+        let category = classify(&e);
+        // A failed package script propagates its own exit status so
+        // `utoo run <script>` mirrors the script: a non-zero `exit N` becomes
+        // N, and a signal death (e.g. SIGPIPE from `script | head`) becomes
+        // 128+N. JSON invocations always use the stable category code.
+        let exit_code = if invocation::json() {
+            category.exit_code() as i32
+        } else {
+            e.downcast_ref::<ScriptExit>()
+                .map_or_else(|| category.exit_code() as i32, |s| s.code)
+        };
+        if invocation::json() {
+            let cli_error = e.downcast_ref::<CliError>();
+            let message = cli_error.map_or_else(|| e.to_string(), |e| e.message().to_string());
+            let causes = e
+                .chain()
+                .skip(1)
+                .map(ToString::to_string)
+                .collect::<Vec<_>>();
+            let script_details = script_failure_details(&e);
+            let dependency_details = dependency_failure_details(&e);
+            let code = cli_error.map_or_else(
+                || {
+                    if script_details.is_some() {
+                        "script_failed"
+                    } else if dependency_details.is_some() {
+                        "dependency_resolution_failed"
+                    } else {
+                        "operation_failed"
+                    }
+                },
+                CliError::code,
+            );
+            let report = presenter::ErrorReport {
+                command: invocation::command(),
+                subcommand: invocation::subcommand(),
+                category,
+                code,
+                exit_code: category.exit_code(),
+                message: &message,
+                causes: &causes,
+                suggestion: cli_error.and_then(CliError::suggestion),
+                partial_result: cli_error.and_then(CliError::partial_result),
+                details: cli_error
+                    .and_then(CliError::details)
+                    .or(script_details.as_ref())
+                    .or(dependency_details.as_ref()),
+                log_path: get_log_file_path().map(|path| path.to_string_lossy().into_owned()),
+            };
+            let result = presenter::write_error(&mut io::stderr().lock(), &report);
+            if result.is_err() {
+                process::exit(exit_code);
+            }
+        } else if let Some(chain) = format_resolve_chain(&e) {
+            eprintln!("error: {e:#}\n\n{chain}");
+        } else {
+            eprintln!("error: {e:#}");
+        }
+        if !invocation::quiet()
+            && let Some(log_path) = get_log_file_path()
+        {
+            eprintln!("Full logs saved to: {}", log_path.display());
+        }
+        process::exit(exit_code);
+    }
+}
+
+async fn async_main() -> Result<()> {
+    let args: Vec<String> = std::env::args().collect();
+    let json_requested = has_flag_before_delimiter(&args, "--json");
+    let no_color_requested = has_flag_before_delimiter(&args, "--no-color");
+    let color = ColorPolicy::from(
+        json_requested || no_color_requested || std::env::var_os("NO_COLOR").is_some(),
+    );
+    color.apply();
+
+    // Preserve the custom root help catalog for human invocations. JSON help is
+    // handled through clap below so stdout remains one machine document.
+    if !json_requested && args.len() > 1 && (args[1] == "-h" || args[1] == "--help") {
+        let config = Config::load(ConfigScope::Local).await?;
+        let config_service = ConfigService::new(config);
+        config_service.print_help()?;
+        return Ok(());
+    }
+
+    log_time(); // Start global timer
+    let cli = match Cli::command()
+        .color(color.clap_choice())
+        .try_get_matches_from(&args)
+        .and_then(|matches| Cli::from_arg_matches(&matches))
+    {
+        Ok(cli) => cli,
+        Err(error) => {
+            if json_requested {
+                match error.kind() {
+                    ClapErrorKind::DisplayHelp | ClapErrorKind::DisplayVersion => {
+                        let command = if error.kind() == ClapErrorKind::DisplayVersion {
+                            "version"
+                        } else {
+                            "help"
+                        };
+                        if command == "version" {
+                            presenter::write(
+                                &mut io::stdout().lock(),
+                                command,
+                                None,
+                                &VersionResult {
+                                    version: APP_VERSION.to_string(),
+                                },
+                            )?;
+                        } else {
+                            presenter::write(
+                                &mut io::stdout().lock(),
+                                command,
+                                None,
+                                &HelpResult {
+                                    target: detect_help_target(&args),
+                                    text: error.to_string().trim_end().to_string(),
+                                },
+                            )?;
+                        }
+                        return Ok(());
+                    }
+                    _ => {
+                        let causes = Vec::new();
+                        presenter::write_error(
+                            &mut io::stderr().lock(),
+                            &presenter::ErrorReport {
+                                command: detect_command(&args),
+                                subcommand: detect_subcommand(&args),
+                                category: ErrorKind::Usage,
+                                code: "invalid_arguments",
+                                exit_code: ErrorKind::Usage.exit_code(),
+                                message: error.to_string().trim(),
+                                causes: &causes,
+                                suggestion: None,
+                                partial_result: None,
+                                details: None,
+                                log_path: None,
+                            },
+                        )?;
+                        process::exit(2);
+                    }
+                }
+            }
+            error.exit();
+        }
+    };
+    let color =
+        ColorPolicy::from(cli.json || cli.no_color || std::env::var_os("NO_COLOR").is_some());
+    color.apply();
+    let verbosity = ConsoleVerbosity::from_flags(cli.verbose, cli.quiet || cli.json);
+    let execute_version = matches!(
+        &cli.command,
+        Some(Commands::Execute { command, .. }) if matches!(command.as_str(), "--version" | "-v")
+    );
+    let command = if cli.version || execute_version {
+        Some("version")
+    } else {
+        cli.command
+            .as_ref()
+            .map(Commands::json_name)
+            .or_else(|| cli.script_name.as_ref().map(|_| "run"))
+            .or_else(|| (cli.command.is_none() && cli.script_name.is_none()).then_some("install"))
+    };
+    let subcommand = cli.command.as_ref().and_then(Commands::json_subcommand);
+    invocation::init(Invocation {
+        output: OutputFormat::from(cli.json),
+        verbosity,
+        color,
+        command,
+        subcommand,
+    });
+
+    // Handle version before the unsupported-command gate: `--json --version`
+    // is itself a machine-readable command result.
+    if cli.version || execute_version {
+        let output = VersionResult {
+            version: APP_VERSION.to_string(),
+        };
+        return presenter::emit("version", &output, || {
+            println!("{APP_VERSION}");
+            Ok(())
+        });
+    }
+
+    if cli.uses_project_package_manager() {
+        handoff_if_needed(
+            &std::env::current_dir()?,
+            &args[1..],
+            cli.registry.clone(),
+            cli.cache_dir.clone(),
+        )
+        .await?;
+    }
+
+    // Handle completions early to avoid unnecessary initialization (tracing, registry, auto-update)
+    if let Some(Commands::Completions { shell }) = cli.command {
+        let shell = shell.or_else(detect_shell_from_env);
+
+        let Some(shell) = shell else {
+            if invocation::json() {
+                return Err(CliError::usage(
+                    "could not detect shell; specify bash, zsh, fish, powershell, or elvish",
+                )
+                .into());
+            }
+            eprintln!(
+                "Could not detect shell. Usage: utoo completions <bash|zsh|fish|powershell|elvish>"
+            );
+            process::exit(2);
+        };
+
+        if invocation::json() {
+            let script =
+                tokio::task::spawn_blocking(move || crate::commands::completions::generate(shell))
+                    .await
+                    .context("Failed to generate shell completions")??;
+            return presenter::emit(
+                "completions",
+                &CompletionsResult {
+                    shell: shell.to_string(),
+                    script,
+                },
+                || Ok(()),
+            );
+        }
+
+        let script =
+            tokio::task::spawn_blocking(move || crate::commands::completions::generate(shell))
+                .await
+                .context("Failed to generate shell completions")??;
+        print!("{script}");
+
+        return Ok(());
+    }
+
+    if cli.json && matches!(&cli.command, Some(Commands::Login)) {
+        return Err(
+            CliError::usage("login requires an interactive browser flow")
+                .with_code("interactive_required")
+                .with_suggestion("run without `--json`")
+                .into(),
+        );
+    }
+
+    // Initialize tracing (replaces set_verbose)
+    let (log_file, _guard) =
+        init_tracing(verbosity, color).context("Failed to initialize logging")?;
+
+    tracing::debug!(
+        log_file = %log_file.display(),
+        ?verbosity,
+        "Logger initialized"
+    );
+
+    // Run --from migration early, before config is cached by init_registry
+    if let Some(Commands::Install(args)) = &cli.command {
+        commands::install::migrate_from(args.from).await?;
+    }
+
+    crate::initialize(InitializeOptions {
+        registry: cli.registry,
+        cache_dir: cli.cache_dir.map(Into::into),
+        legacy_peer_deps: legacy_peer_deps_override(cli.legacy_peer_deps),
+        manifests_concurrency_limit: cli.manifests_concurrency_limit,
+        script_concurrency_limit: cli.script_concurrency_limit,
+    })
+    .await?;
+
+    // Auto update: check cache → update or refresh in background
+    init_auto_update().await;
+
+    match cli.command {
+        Some(Commands::Clean { pattern, yes }) => {
+            let confirmation = ConfirmationPolicy::from(yes);
+            if confirmation.requires_interaction() && !invocation::interactive() {
+                return Err(CliError::usage(
+                    "refusing to prompt for cache deletion in non-interactive mode",
+                )
+                .with_suggestion("rerun with `utoo clean --yes`")
+                .into());
+            }
+            commands::clean::run(&pattern, confirmation).await?;
+            log_time_end(&format!("{pattern} cleaned"));
+        }
+        Some(Commands::Install(args)) => {
+            commands::install::run(args, cli.legacy_peer_deps).await?;
+        }
+        Some(Commands::Uninstall {
+            specs,
+            workspace,
+            ignore_scripts,
+        }) => {
+            commands::uninstall::run(specs, workspace, ScriptPolicy::from(ignore_scripts)).await?;
+        }
+        Some(Commands::Rebuild) => {
+            let cwd = std::env::current_dir()?;
+            commands::rebuild::run(&cwd).await?;
+            log_time_end("All packages rebuilt");
+        }
+        Some(Commands::Deps { workspace_only }) => {
+            commands::deps::run(workspace_only).await?;
+        }
+        Some(Commands::Update(args)) => {
+            commands::update::run(args, ScriptPolicy::Run).await?;
+            log_time_end("All packages updated");
+        }
+        Some(Commands::List { package }) => {
+            let cwd = std::env::current_dir()?;
+            commands::list::run(&cwd, &package).await?;
+        }
+        Some(Commands::Execute { command, args }) => {
+            commands::execute::run(&command, args).await?;
+        }
+        Some(Commands::Run {
+            script,
+            workspace,
+            workspaces,
+            if_present,
+            args,
+        }) => {
+            let missing = if if_present {
+                MissingScript::Skip
+            } else {
+                MissingScript::Fail
+            };
+            commands::run::run(
+                script.as_deref(),
+                WorkspaceFilter::from_flags(workspace, workspaces),
+                missing,
+                (!args.is_empty()).then_some(args),
+            )
+            .await?;
+        }
+        Some(Commands::View { package }) => {
+            commands::view::run(&package).await?;
+        }
+        Some(Commands::Link { packages, prefix }) => {
+            commands::link::run(packages, prefix).await?;
+        }
+        Some(Commands::Init { yes }) => {
+            let mode = InitMode::from(yes);
+            if mode.requires_interaction() && !invocation::interactive() {
+                return Err(CliError::usage(
+                    "refusing to prompt for package metadata in non-interactive mode",
+                )
+                .with_suggestion("re-run with `utoo init --yes`")
+                .into());
+            }
+            let output = if invocation::json() {
+                InitOutput::Machine
+            } else {
+                InitOutput::Human
+            };
+            commands::init::run(mode, output, None).await?;
+            log_time_end("package.json created");
+            if invocation::json() {
+                let path = std::env::current_dir()?.join("package.json");
+                let package: serde_json::Value =
+                    serde_json::from_str(&crate::fs::read_to_string(&path).await?)?;
+                presenter::emit(
+                    "init",
+                    &InitResult {
+                        path: path.to_string_lossy().into_owned(),
+                        name: package["name"].as_str().unwrap_or_default().to_string(),
+                        version: package["version"].as_str().unwrap_or_default().to_string(),
+                    },
+                    || Ok(()),
+                )?;
+            }
+        }
+        Some(Commands::Pack { path, dry_run }) => {
+            commands::pack::run(path, dry_run.into()).await?;
+            log_time_end("Pack complete");
+        }
+        Some(Commands::Publish {
+            tag,
+            dry_run,
+            otp,
+            access,
+            // utoo performs no Git cleanliness checks, so `--no-git-checks` is a
+            // documented no-op accepted for pnpm/npm compatibility.
+            no_git_checks: _,
+            provenance,
+        }) => {
+            // `--workspace`/`--filter` selects member(s); empty means the current
+            // package. `--workspaces` is intentionally NOT honored here to avoid
+            // an accidental publish of every member.
+            let filter = if cli.workspace.is_empty() {
+                WorkspaceFilter::Current
+            } else {
+                WorkspaceFilter::Selected(cli.workspace)
+            };
+            commands::publish::run(
+                tag.as_deref(),
+                dry_run.into(),
+                otp.as_deref(),
+                access,
+                filter,
+                ProvenancePolicy::from(provenance),
+            )
+            .await?;
+        }
+        Some(Commands::Ping { registry }) => {
+            commands::ping::run(registry.as_deref()).await?;
+        }
+        Some(Commands::Login) => {
+            commands::login::run().await?;
+        }
+        Some(Commands::Whoami) => {
+            commands::whoami::run().await?;
+        }
+        Some(Commands::Logout) => {
+            commands::logout::run().await?;
+        }
+        Some(Commands::Config { command }) => {
+            commands::config::run(command).await?;
+        }
+        None => match cli.script_name {
+            // A bare `utoo <name>`: custom command from config, else script
+            Some(script_name) => {
+                commands::run::fallback(
+                    &script_name,
+                    WorkspaceFilter::from_flags(cli.workspace, cli.workspaces),
+                    cli.script_args,
+                )
+                .await?;
+            }
+            // Default to install if no arguments
+            None => {
+                commands::install::current_project(ScriptPolicy::from(cli.ignore_scripts)).await?
+            }
+        },
+        // Completions is handled early before initialization
+        Some(Commands::Completions { .. }) => unreachable!(),
+    }
+
+    Ok(())
+}
+
+fn has_flag_before_delimiter(args: &[String], flag: &str) -> bool {
+    args.iter()
+        .take_while(|arg| arg.as_str() != "--")
+        .any(|arg| arg == flag)
+}
+
+// `ArgAction::SetTrue` materializes an absent flag as `Some(false)`. The CLI
+// historically treated that as no override so the configured/default peer
+// policy remains in effect; embedders can still pass `Some(false)` directly to
+// `initialize` when they intentionally want to include peer dependencies.
+fn legacy_peer_deps_override(value: Option<bool>) -> Option<bool> {
+    value.filter(|enabled| *enabled)
+}
+
+fn detect_help_target(args: &[String]) -> Option<HelpTarget> {
+    let command = detect_command(args)?;
+    (command != "help" && command != "version").then(|| HelpTarget {
+        command: command.to_string(),
+        subcommand: detect_subcommand(args).map(str::to_string),
+    })
+}
+
+fn detect_command(args: &[String]) -> Option<&'static str> {
+    detect_command_token(args).map(|(command, _)| command)
+}
+
+fn detect_command_token(args: &[String]) -> Option<(&'static str, usize)> {
+    let mut index = 1;
+    while index < args.len() {
+        let value = args[index].as_str();
+        if value == "--" {
+            return None;
+        }
+        if matches!(
+            value,
+            "--registry"
+                | "--cache-dir"
+                | "--manifests-concurrency-limit"
+                | "--script-concurrency-limit"
+                | "--workspace"
+                | "--filter"
+        ) {
+            index += 2;
+            continue;
+        }
+        if value.starts_with('-') {
+            index += 1;
+            continue;
+        }
+        let command = match value {
+            "i" | "add" | "install" => "install",
+            "un" | "uninstall" | "remove" | "rm" => "uninstall",
+            "rb" | "rebuild" => "rebuild",
+            "c" | "clean" => "clean",
+            "d" | "deps" => "deps",
+            "u" | "update" => "update",
+            "ls" | "list" => "list",
+            "r" | "run" => "run",
+            "x" | "execute" => "execute",
+            "v" | "view" | "info" | "show" => "view",
+            "ln" | "link" => "link",
+            "pk" | "pm-pack" => "pack",
+            "pub" | "publish" => "publish",
+            "pg" | "ping" => "ping",
+            "lg" | "login" => "login",
+            "who" | "whoami" => "whoami",
+            "lo" | "logout" => "logout",
+            "cfg" | "config" => "config",
+            "create" | "init" => "init",
+            "cmp" | "completions" => "completions",
+            _ => "run",
+        };
+        return Some((command, index));
+    }
+    None
+}
+
+fn detect_subcommand(args: &[String]) -> Option<&'static str> {
+    let (command, index) = detect_command_token(args)?;
+    if command != "config" {
+        return None;
+    }
+    let mut index = index + 1;
+    while index < args.len() {
+        let value = args[index].as_str();
+        if value == "--" {
+            return None;
+        }
+        if matches!(
+            value,
+            "--registry"
+                | "--cache-dir"
+                | "--manifests-concurrency-limit"
+                | "--script-concurrency-limit"
+        ) {
+            index += 2;
+            continue;
+        }
+        if value.starts_with('-') {
+            index += 1;
+            continue;
+        }
+        return match value {
+            "set" => Some("set"),
+            "get" => Some("get"),
+            "list" => Some("list"),
+            _ => None,
+        };
+    }
+    None
+}
+
+fn dependency_failure_details(error: &anyhow::Error) -> Option<ErrorDetails> {
+    let chain = resolve_chain(error)?;
+    let (requested, required_by) = chain.split_last()?;
+    Some(ErrorDetails::Dependency {
+        package: RequestedPackage {
+            name: requested.0.clone(),
+            spec: requested.1.clone(),
+        },
+        required_by: required_by
+            .iter()
+            .map(|(name, version)| RequiredBy {
+                name: (!name.is_empty()).then(|| name.clone()),
+                version: (!version.is_empty()).then(|| version.clone()),
+            })
+            .collect(),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use clap::Parser;
+
+    use super::*;
+
+    #[test]
+    fn absent_legacy_peer_flag_does_not_override_the_default() {
+        let absent = Cli::try_parse_from(["utoo"]).expect("bare CLI should parse");
+        assert_eq!(absent.legacy_peer_deps, Some(false));
+        assert_eq!(legacy_peer_deps_override(absent.legacy_peer_deps), None);
+
+        let present = Cli::try_parse_from(["utoo", "--legacy-peer-deps"])
+            .expect("legacy peer flag should parse");
+        assert_eq!(
+            legacy_peer_deps_override(present.legacy_peer_deps),
+            Some(true)
+        );
+    }
+}
diff --git a/crates/pm/src/cmd/mod.rs b/crates/pm/src/cmd/mod.rs
deleted file mode 100644
index 59150b9989..0000000000
--- a/crates/pm/src/cmd/mod.rs
+++ /dev/null
@@ -1,34 +0,0 @@
-//! CLI subcommand handlers — the thin dispatch layer.
-//!
-//! Each module is one `utoo`/`ut` subcommand. It assembles parameters from the
-//! parsed [`Cli`](crate::cli) and delegates to [`crate::service`]; no business
-//! logic lives here (the `cmd/` layering rule in AGENTS.md).
-//!
-//! ```text
-//!   main.rs ──(parse Cli, route on Commands)──► cmd::<subcommand>
-//!                                                    │ assemble args,
-//!                                                    │ map flags → enums
-//!                                                    ▼
-//!                                               crate::service::<logic>
-//! ```
-//!
-//! Representative routes: install/update → `service::install` ·
-//! run → `service::script` · publish → `service::{publish,pm_pack}` ·
-//! deps/list → `service::dependency_graph` · config → `service::config`.
-
-pub mod clean;
-pub mod config;
-pub mod deps;
-pub mod install;
-pub mod link;
-pub mod list;
-pub mod login;
-pub mod logout;
-pub mod ping;
-pub mod pm_pack;
-pub mod publish;
-pub mod rebuild;
-pub mod run;
-pub mod update;
-pub mod view;
-pub mod whoami;
diff --git a/crates/pm/src/cmd/clean.rs b/crates/pm/src/commands/clean.rs
similarity index 96%
rename from crates/pm/src/cmd/clean.rs
rename to crates/pm/src/commands/clean.rs
index 470d22712f..90bc1fb7a8 100644
--- a/crates/pm/src/cmd/clean.rs
+++ b/crates/pm/src/commands/clean.rs
@@ -1,3 +1,5 @@
+//! Cache cleanup command.
+
 use anyhow::Result;
 
 use crate::error::{CliError, ErrorKind};
@@ -10,7 +12,7 @@ use crate::util::format_print::confirm;
 use crate::util::invocation;
 use crate::util::presenter::emit;
 
-pub async fn clean(pattern: &str, confirmation: ConfirmationPolicy) -> Result<()> {
+pub async fn run(pattern: &str, confirmation: ConfirmationPolicy) -> Result<()> {
     let to_delete = collect_cache_entries(pattern).await?;
 
     if to_delete.is_empty() {
diff --git a/crates/pm/src/commands/completions.rs b/crates/pm/src/commands/completions.rs
new file mode 100644
index 0000000000..2564430708
--- /dev/null
+++ b/crates/pm/src/commands/completions.rs
@@ -0,0 +1,11 @@
+//! Shell-completion generation.
+
+use anyhow::Context;
+
+/// Generate a UTF-8 shell-completion script.
+pub fn generate(shell: clap_complete::Shell) -> anyhow::Result<String> {
+    let mut output = Vec::new();
+    let mut command = crate::command();
+    clap_complete::generate(shell, &mut command, crate::constants::APP_NAME, &mut output);
+    String::from_utf8(output).context("Generated completion script is not UTF-8")
+}
diff --git a/crates/pm/src/cmd/config.rs b/crates/pm/src/commands/config.rs
similarity index 89%
rename from crates/pm/src/cmd/config.rs
rename to crates/pm/src/commands/config.rs
index 0d0099b462..224db5ecfa 100644
--- a/crates/pm/src/cmd/config.rs
+++ b/crates/pm/src/commands/config.rs
@@ -1,9 +1,11 @@
+//! Persistent package-manager configuration.
+
 use std::collections::{BTreeMap, HashMap};
 
 use anyhow::{Result, anyhow};
 use serde_json::Value;
 
-use crate::cli::ConfigCommands;
+pub use crate::cli::ConfigCommands as Command;
 use crate::error::CliError;
 use crate::model::cli_output::{ConfigGetResult, ConfigListResult, ConfigSetResult};
 use crate::util::cli_enum::ConfigScope;
@@ -11,17 +13,15 @@ use crate::util::config_file::Config;
 use crate::util::presenter::emit;
 
 /// Entry point for the `config` subcommand.
-pub async fn run(command: ConfigCommands) -> Result<()> {
+pub async fn run(command: Command) -> Result<()> {
     match command {
-        ConfigCommands::Set { key, value, global } => {
-            handle_config_set(key, value, global.into()).await
-        }
-        ConfigCommands::Get {
+        Command::Set { key, value, global } => handle_config_set(key, value, global.into()).await,
+        Command::Get {
             key,
             global,
             override_values,
         } => handle_config_get(key, global.into(), override_values).await,
-        ConfigCommands::List { global } => handle_config_list(global.into()).await,
+        Command::List { global } => handle_config_list(global.into()).await,
     }
 }
 
@@ -33,7 +33,7 @@ fn parse_key_val(s: &str) -> Result<(String, String)> {
     Ok((s[..pos].to_string(), s[pos + 1..].to_string()))
 }
 
-pub async fn handle_config_set(key: String, value: String, scope: ConfigScope) -> Result<()> {
+async fn handle_config_set(key: String, value: String, scope: ConfigScope) -> Result<()> {
     let mut config = Config::load(scope).await?;
     config.set(&key, value.clone(), scope)?;
     let label = if scope == ConfigScope::Global {
@@ -51,7 +51,7 @@ pub async fn handle_config_set(key: String, value: String, scope: ConfigScope) -
     })
 }
 
-pub async fn handle_config_get(
+async fn handle_config_get(
     key: String,
     scope: ConfigScope,
     override_values: Vec<String>,
@@ -90,7 +90,7 @@ pub async fn handle_config_get(
     Ok(())
 }
 
-pub async fn handle_config_list(scope: ConfigScope) -> Result<()> {
+async fn handle_config_list(scope: ConfigScope) -> Result<()> {
     let config = Config::load(scope).await?;
     let config_path = match scope {
         ConfigScope::Global => config.get_global_config_path()?,
diff --git a/crates/pm/src/cmd/deps.rs b/crates/pm/src/commands/deps.rs
similarity index 92%
rename from crates/pm/src/cmd/deps.rs
rename to crates/pm/src/commands/deps.rs
index 0cfa90fdeb..f4dd74731e 100644
--- a/crates/pm/src/cmd/deps.rs
+++ b/crates/pm/src/commands/deps.rs
@@ -1,3 +1,5 @@
+//! Dependency resolution command.
+
 use std::path::Path;
 use std::time::Instant;
 
@@ -45,7 +47,7 @@ pub async fn run(workspace_only: bool) -> Result<()> {
     emit("deps", &output, || Ok(()))
 }
 
-pub async fn build_deps(cwd: &Path) -> Result<PackageLock> {
+pub(crate) async fn build_deps(cwd: &Path) -> Result<PackageLock> {
     start_progress_bar();
     let resolve_start = Instant::now();
 
@@ -59,7 +61,7 @@ pub async fn build_deps(cwd: &Path) -> Result<PackageLock> {
     Ok(lock)
 }
 
-pub async fn build_workspace(cwd: &Path) -> Result<crate::service::workspace::WorkspaceJson> {
+async fn build_workspace(cwd: &Path) -> Result<crate::service::workspace::WorkspaceJson> {
     let workspace_file = WorkspaceService::build_workspace_json(cwd).await?;
     let content = serde_json::to_string_pretty(&workspace_file)?;
     crate::fs::write(cwd.join("workspace.json"), content)
diff --git a/crates/pm/src/commands/execute.rs b/crates/pm/src/commands/execute.rs
new file mode 100644
index 0000000000..4559b91875
--- /dev/null
+++ b/crates/pm/src/commands/execute.rs
@@ -0,0 +1,6 @@
+//! Package binary execution command.
+
+/// Execute a binary from a package, equivalent to `utoo execute`.
+pub async fn run(command: &str, args: Vec<String>) -> anyhow::Result<()> {
+    crate::service::execute::execute_package(command, args).await
+}
diff --git a/crates/pm/src/commands/init.rs b/crates/pm/src/commands/init.rs
new file mode 100644
index 0000000000..ba098c1d08
--- /dev/null
+++ b/crates/pm/src/commands/init.rs
@@ -0,0 +1,15 @@
+//! Package initialization command.
+
+use std::path::PathBuf;
+
+pub use crate::service::init::InitOutput;
+
+/// Initialize a package in `project_dir`, or in the current directory when it
+/// is omitted.
+pub async fn run(
+    mode: crate::types::InitMode,
+    output: InitOutput,
+    project_dir: Option<PathBuf>,
+) -> anyhow::Result<()> {
+    crate::service::init::init(mode, output, project_dir.as_deref()).await
+}
diff --git a/crates/pm/src/cmd/install.rs b/crates/pm/src/commands/install.rs
similarity index 85%
rename from crates/pm/src/cmd/install.rs
rename to crates/pm/src/commands/install.rs
index 2f790d2dbe..00a0cf3219 100644
--- a/crates/pm/src/cmd/install.rs
+++ b/crates/pm/src/commands/install.rs
@@ -1,3 +1,5 @@
+//! Dependency installation commands.
+
 use std::collections::{BTreeMap, HashSet};
 use std::path::Path;
 
@@ -6,11 +8,11 @@ use clap::Args;
 use utoo_ruborist::lock::PackageLock;
 use utoo_ruborist::spec::PackageSpec;
 
-use crate::helper::migrate::{FromPm, migrate_from_pnpm};
+pub use crate::helper::migrate::FromPm;
+use crate::helper::migrate::migrate_from_pnpm;
 use crate::helper::workspace::init_project_root;
 use crate::model::cli_output::{
     DependencyOperation, DependencyScope, DependencySummary, InstallResult, PackageVersion,
-    UninstallResult,
 };
 use crate::service::install::InstallService;
 use crate::service::script::ScriptOutput;
@@ -75,6 +77,8 @@ pub struct InstallArgs {
     pub from: Option<FromPm>,
 }
 
+pub use InstallArgs as Options;
+
 /// Entry point for the `install` command.
 ///
 /// Folds `--production` and `--legacy-peer-deps` into the omit set, then
@@ -115,7 +119,7 @@ pub async fn run(args: InstallArgs, legacy_peer_deps: Option<bool>) -> Result<()
     } else if scope == InstallScope::Global {
         // For global installs, process packages one by one
         for spec in args.specs.iter() {
-            install_global_package(spec, args.prefix.as_deref()).await?;
+            global(spec, args.prefix.as_deref()).await?;
         }
         log_time_end(&pluralized_package_count(args.specs.len(), "installed"));
     } else {
@@ -160,56 +164,9 @@ pub async fn run(args: InstallArgs, legacy_peer_deps: Option<bool>) -> Result<()
     emit("install", &output, || Ok(()))
 }
 
-/// Entry point for the `uninstall` command.
-pub async fn uninstall(
-    specs: Vec<String>,
-    workspace: Option<String>,
-    scripts: ScriptPolicy,
-) -> Result<()> {
-    if specs.is_empty() {
-        anyhow::bail!("Package specification is required for uninstall");
-    }
-
-    let machine = invocation::json();
-    let root_path = if machine {
-        let cwd = std::env::current_dir()?;
-        Some(init_project_root(&cwd).await?)
-    } else {
-        None
-    };
-    let before = load_lock_snapshot(root_path.as_deref()).await;
-    let removed = before
-        .as_ref()
-        .map(|lock| direct_packages(lock, &specs))
-        .unwrap_or_default();
-    let spec_refs: Vec<&str> = specs.iter().map(|s| s.as_str()).collect();
-    update_packages(
-        PackageAction::Remove,
-        &spec_refs,
-        workspace.clone(),
-        scripts,
-        SaveType::Prod,
-    )
-    .await?;
-    log_time_end(&pluralized_package_count(specs.len(), "uninstalled"));
-    if !machine {
-        return Ok(());
-    }
-    let after = load_lock_snapshot(root_path.as_deref()).await;
-    let output = UninstallResult {
-        operation: DependencyOperation::Remove,
-        scope: DependencyScope::Local,
-        workspace,
-        requested: specs,
-        removed,
-        summary: dependency_summary(before.as_ref(), after.as_ref(), 0),
-    };
-    emit("uninstall", &output, || Ok(()))
-}
-
 /// Install all dependencies of the project containing the current directory.
 /// Shared by bare `utoo` and `utoo install` without specs.
-pub async fn install_cwd(scripts: ScriptPolicy) -> Result<()> {
+pub async fn current_project(scripts: ScriptPolicy) -> Result<()> {
     let download_baseline = DownloadBaseline::capture();
     let machine = invocation::json();
     let root_path = if machine {
@@ -245,7 +202,7 @@ pub async fn install_cwd(scripts: ScriptPolicy) -> Result<()> {
 async fn install_cwd_inner(scripts: ScriptPolicy) -> Result<()> {
     let cwd = std::env::current_dir()?;
     let root_path = init_project_root(&cwd).await?;
-    install(scripts, &root_path).await?;
+    project(&root_path, scripts).await?;
     log_time_end("All packages installed");
     Ok(())
 }
@@ -402,7 +359,7 @@ pub async fn migrate_from(from: Option<FromPm>) -> Result<()> {
     Ok(())
 }
 
-pub async fn update_packages(
+pub(super) async fn update_packages(
     action: PackageAction,
     specs: &[&str],
     workspace: Option<String>,
@@ -422,11 +379,11 @@ pub async fn update_packages(
     .await
 }
 
-pub async fn install(scripts: ScriptPolicy, root_path: &Path) -> Result<()> {
+pub async fn project(root_path: &Path, scripts: ScriptPolicy) -> Result<()> {
     install_with_mode(scripts, root_path, ReifyMode::Incremental).await
 }
 
-pub async fn install_with_mode(
+pub(super) async fn install_with_mode(
     scripts: ScriptPolicy,
     root_path: &Path,
     mode: ReifyMode,
@@ -435,7 +392,7 @@ pub async fn install_with_mode(
     InstallService::install_with_mode(scripts, root_path, &omit, mode, script_output()).await
 }
 
-pub async fn install_global_package(npm_spec: &str, prefix: Option<&str>) -> Result<()> {
+pub async fn global(npm_spec: &str, prefix: Option<&str>) -> Result<()> {
     // Parameter validation
     if npm_spec.trim().is_empty() {
         anyhow::bail!("Package specification cannot be empty");
@@ -463,10 +420,10 @@ mod tests {
     #[tokio::test]
     async fn test_install_global_package_empty_spec() {
         // Test installing with empty package spec
-        let result = install_global_package("", None).await;
+        let result = global("", None).await;
         assert!(result.is_err(), "Should fail with empty package spec");
 
-        let result = install_global_package("   ", None).await;
+        let result = global("   ", None).await;
         assert!(
             result.is_err(),
             "Should fail with whitespace-only package spec"
@@ -486,10 +443,4 @@ mod tests {
         .await;
         assert!(result.is_err(), "Should fail with empty specs");
     }
-
-    #[tokio::test]
-    async fn test_uninstall_empty_specs() {
-        let result = uninstall(Vec::new(), None, ScriptPolicy::Run).await;
-        assert!(result.is_err(), "Should fail with empty specs");
-    }
 }
diff --git a/crates/pm/src/cmd/link.rs b/crates/pm/src/commands/link.rs
similarity index 97%
rename from crates/pm/src/cmd/link.rs
rename to crates/pm/src/commands/link.rs
index 997a6fa665..6634172f45 100644
--- a/crates/pm/src/cmd/link.rs
+++ b/crates/pm/src/commands/link.rs
@@ -1,8 +1,10 @@
+//! Package linking command.
+
 use std::path::Path;
 
 use anyhow::{Context, Result};
 
-use crate::cmd::install::install;
+use crate::commands::install::project;
 use crate::error::{CliError, classify};
 use crate::helper::global_bin::{get_global_bin_dir, get_global_package_dir};
 use crate::helper::workspace::update_cwd_to_project;
@@ -61,7 +63,7 @@ pub async fn run(packages: Option<Vec<String>>, prefix: Option<String>) -> Resul
 }
 
 /// Link current package to global (equivalent to npm link without args)
-pub async fn link_current_to_global(cwd: &Path, prefix: Option<&str>) -> Result<LinkEntry> {
+async fn link_current_to_global(cwd: &Path, prefix: Option<&str>) -> Result<LinkEntry> {
     // Resolve the effective prefix: CLI flag > UTOO_PREFIX env > config.
     let prefix = resolve_global_prefix(prefix).await;
     let prefix = prefix.as_deref();
@@ -81,7 +83,7 @@ pub async fn link_current_to_global(cwd: &Path, prefix: Option<&str>) -> Result<
     }
 
     // Install dependencies
-    install(ScriptPolicy::Run, &project_path)
+    project(&project_path, ScriptPolicy::Run)
         .await
         .context("Failed to prepare dependencies for package to link")?;
 
@@ -116,7 +118,7 @@ pub async fn link_current_to_global(cwd: &Path, prefix: Option<&str>) -> Result<
 }
 
 /// Link a global package to local node_modules (equivalent to npm link pkg_name)
-pub async fn link_global_to_local(
+async fn link_global_to_local(
     cwd: &Path,
     package_name: &str,
     prefix: Option<&str>,
diff --git a/crates/pm/src/cmd/list.rs b/crates/pm/src/commands/list.rs
similarity index 96%
rename from crates/pm/src/cmd/list.rs
rename to crates/pm/src/commands/list.rs
index 0c3f05f0f1..ec7207701c 100644
--- a/crates/pm/src/cmd/list.rs
+++ b/crates/pm/src/commands/list.rs
@@ -1,3 +1,5 @@
+//! Installed dependency inspection command.
+
 use std::path::Path;
 
 use anyhow::{Context, Result};
@@ -9,7 +11,7 @@ use crate::util::invocation;
 use crate::util::presenter::emit;
 
 /// List dependency information, similar to npm list
-pub async fn list_dependencies(cwd: &Path, package_name: &str) -> Result<()> {
+pub async fn run(cwd: &Path, package_name: &str) -> Result<()> {
     tracing::debug!("Starting dependency listing...");
 
     // Find package-lock.json file
@@ -134,7 +136,7 @@ mod tests {
     async fn test_list_dependencies_lockfile_missing_error() {
         // A temp dir with no package-lock.json should produce a helpful error.
         let dir = tempfile::tempdir().unwrap();
-        let result = list_dependencies(dir.path(), "some-package").await;
+        let result = run(dir.path(), "some-package").await;
         assert!(result.is_err());
         let err = result.unwrap_err().to_string();
         assert!(
diff --git a/crates/pm/src/cmd/login.rs b/crates/pm/src/commands/login.rs
similarity index 89%
rename from crates/pm/src/cmd/login.rs
rename to crates/pm/src/commands/login.rs
index 7afcad863d..4f2e0d7d0f 100644
--- a/crates/pm/src/cmd/login.rs
+++ b/crates/pm/src/commands/login.rs
@@ -1,10 +1,12 @@
+//! Registry login command.
+
 use anyhow::Result;
 use colored::Colorize;
 
 use crate::service::auth;
 use crate::util::user_config::get_registry;
 
-pub async fn login() -> Result<()> {
+pub async fn run() -> Result<()> {
     let registry = get_registry();
 
     println!("Login to {}", registry.cyan());
diff --git a/crates/pm/src/cmd/logout.rs b/crates/pm/src/commands/logout.rs
similarity index 90%
rename from crates/pm/src/cmd/logout.rs
rename to crates/pm/src/commands/logout.rs
index b0566be935..0bf9f672ff 100644
--- a/crates/pm/src/cmd/logout.rs
+++ b/crates/pm/src/commands/logout.rs
@@ -1,3 +1,5 @@
+//! Registry logout command.
+
 use anyhow::Result;
 use colored::Colorize;
 
@@ -6,7 +8,7 @@ use crate::service::auth;
 use crate::util::presenter::emit;
 use crate::util::user_config::get_registry;
 
-pub async fn logout() -> Result<()> {
+pub async fn run() -> Result<()> {
     let registry = get_registry();
     let token = auth::require_token(&registry).await?;
 
diff --git a/crates/pm/src/commands/mod.rs b/crates/pm/src/commands/mod.rs
new file mode 100644
index 0000000000..b46fe2710b
--- /dev/null
+++ b/crates/pm/src/commands/mod.rs
@@ -0,0 +1,35 @@
+//! Package-manager commands shared by the CLI and embedded hosts.
+//!
+//! Each module is one `utoo`/`ut` capability. Command handlers own the public
+//! boundary and delegate business logic to the crate-private service layer.
+//!
+//! ```text
+//!   CLI adapter ─┐
+//!                ├──► commands::<capability> ──► crate::service::<logic>
+//!   embedder ────┘
+//! ```
+//!
+//! Representative routes: install/update → `service::install` ·
+//! run → `service::script` · publish → `service::{publish,pm_pack}` ·
+//! deps/list → `service::dependency_graph` · config → `service::config`.
+
+pub mod clean;
+pub mod completions;
+pub mod config;
+pub mod deps;
+pub mod execute;
+pub mod init;
+pub mod install;
+pub mod link;
+pub mod list;
+pub mod login;
+pub mod logout;
+pub mod pack;
+pub mod ping;
+pub mod publish;
+pub mod rebuild;
+pub mod run;
+pub mod uninstall;
+pub mod update;
+pub mod view;
+pub mod whoami;
diff --git a/crates/pm/src/cmd/pm_pack.rs b/crates/pm/src/commands/pack.rs
similarity index 95%
rename from crates/pm/src/cmd/pm_pack.rs
rename to crates/pm/src/commands/pack.rs
index 8782a34f2f..92a162615c 100644
--- a/crates/pm/src/cmd/pm_pack.rs
+++ b/crates/pm/src/commands/pack.rs
@@ -1,3 +1,5 @@
+//! Package tarball creation command.
+
 use anyhow::{Context, Result};
 use colored::Colorize;
 use std::io::{self, Write};
@@ -11,7 +13,7 @@ use crate::util::format_print::print_pack_details;
 use crate::util::invocation;
 use crate::util::presenter::emit;
 
-pub async fn pack(path: Option<String>, mode: RunMode) -> Result<()> {
+pub async fn run(path: Option<String>, mode: RunMode) -> Result<()> {
     let package_root = if let Some(p) = path {
         PathBuf::from(p)
     } else {
diff --git a/crates/pm/src/cmd/ping.rs b/crates/pm/src/commands/ping.rs
similarity index 95%
rename from crates/pm/src/cmd/ping.rs
rename to crates/pm/src/commands/ping.rs
index c97f186887..a6843d4367 100644
--- a/crates/pm/src/cmd/ping.rs
+++ b/crates/pm/src/commands/ping.rs
@@ -1,3 +1,5 @@
+//! Registry connectivity command.
+
 use anyhow::Result;
 use colored::Colorize;
 
@@ -9,7 +11,7 @@ use crate::util::presenter::emit;
 use crate::util::registry::ping_registry;
 use crate::util::user_config::{detect_supports_semver, get_registry};
 
-pub async fn ping(registry: Option<&str>) -> Result<()> {
+pub async fn run(registry: Option<&str>) -> Result<()> {
     let registry = registry.map(String::from).unwrap_or_else(get_registry);
 
     if !invocation::json() {
diff --git a/crates/pm/src/cmd/publish.rs b/crates/pm/src/commands/publish.rs
similarity index 99%
rename from crates/pm/src/cmd/publish.rs
rename to crates/pm/src/commands/publish.rs
index 01327c9f48..f7ff11d740 100644
--- a/crates/pm/src/cmd/publish.rs
+++ b/crates/pm/src/commands/publish.rs
@@ -1,3 +1,5 @@
+//! Package publishing command.
+
 use anyhow::{Context, Result};
 use colored::Colorize;
 use std::collections::HashMap;
@@ -27,7 +29,7 @@ use crate::{error::CliError, error::classify};
 /// is published. With `--filter` the matching workspace member(s) are resolved
 /// from the workspace root and published in topological order, so a member can
 /// be published from the repo root without `cd`-ing into its directory.
-pub async fn publish(
+pub async fn run(
     tag: Option<&str>,
     mode: RunMode,
     otp: Option<&str>,
diff --git a/crates/pm/src/cmd/rebuild.rs b/crates/pm/src/commands/rebuild.rs
similarity index 94%
rename from crates/pm/src/cmd/rebuild.rs
rename to crates/pm/src/commands/rebuild.rs
index f037200f7b..9f1e5cd231 100644
--- a/crates/pm/src/cmd/rebuild.rs
+++ b/crates/pm/src/commands/rebuild.rs
@@ -1,3 +1,5 @@
+//! Dependency lifecycle-script rebuild command.
+
 use crate::helper::lock::ensure_package_lock;
 use crate::model::cli_output::{DependencyOperation, RebuildResult, RebuildSummary};
 use crate::service::rebuild::RebuildService;
@@ -9,7 +11,7 @@ use anyhow::Result;
 use std::path::Path;
 use std::time::Instant;
 
-pub async fn rebuild(root_path: &Path) -> Result<()> {
+pub async fn run(root_path: &Path) -> Result<()> {
     start_progress_bar();
     let resolve_start = Instant::now();
     let package_lock = ensure_package_lock(root_path).await?;
diff --git a/crates/pm/src/cmd/run.rs b/crates/pm/src/commands/run.rs
similarity index 99%
rename from crates/pm/src/cmd/run.rs
rename to crates/pm/src/commands/run.rs
index 11935416ad..f65a202912 100644
--- a/crates/pm/src/cmd/run.rs
+++ b/crates/pm/src/commands/run.rs
@@ -1,3 +1,5 @@
+//! Package-script execution command.
+
 use anyhow::{Context, Result};
 use colored::Colorize;
 use std::process::Stdio;
@@ -81,7 +83,7 @@ pub async fn run(
 /// Fallback for `utoo <name>` when `<name>` is not a built-in subcommand:
 /// prefer a custom command from the config, otherwise run `<name>` as a
 /// package.json script.
-pub async fn run_fallback(
+pub async fn fallback(
     script_name: &str,
     filter: WorkspaceFilter,
     script_args: Vec<String>,
diff --git a/crates/pm/src/commands/uninstall.rs b/crates/pm/src/commands/uninstall.rs
new file mode 100644
index 0000000000..ca01e6301c
--- /dev/null
+++ b/crates/pm/src/commands/uninstall.rs
@@ -0,0 +1,73 @@
+//! Dependency removal command.
+
+use anyhow::Result;
+
+use super::install::{dependency_summary, direct_packages, load_lock_snapshot, update_packages};
+use crate::helper::workspace::init_project_root;
+use crate::model::cli_output::{DependencyOperation, DependencyScope, UninstallResult};
+use crate::util::cli_enum::{PackageAction, SaveType, ScriptPolicy};
+use crate::util::format_print::pluralized_package_count;
+use crate::util::invocation;
+use crate::util::logger::log_time_end;
+use crate::util::presenter::emit;
+
+/// Remove dependencies from the current project.
+pub async fn run(
+    specs: Vec<String>,
+    workspace: Option<String>,
+    scripts: ScriptPolicy,
+) -> Result<()> {
+    if specs.is_empty() {
+        anyhow::bail!("Package specification is required for uninstall");
+    }
+
+    let machine = invocation::json();
+    let root_path = if machine {
+        let cwd = std::env::current_dir()?;
+        Some(init_project_root(&cwd).await?)
+    } else {
+        None
+    };
+    let before = load_lock_snapshot(root_path.as_deref()).await;
+    let removed = before
+        .as_ref()
+        .map(|lock| direct_packages(lock, &specs))
+        .unwrap_or_default();
+    let spec_refs = specs.iter().map(String::as_str).collect::<Vec<_>>();
+    update_packages(
+        PackageAction::Remove,
+        &spec_refs,
+        workspace.clone(),
+        scripts,
+        SaveType::Prod,
+    )
+    .await?;
+    log_time_end(&pluralized_package_count(specs.len(), "uninstalled"));
+    if !machine {
+        return Ok(());
+    }
+    let after = load_lock_snapshot(root_path.as_deref()).await;
+    emit(
+        "uninstall",
+        &UninstallResult {
+            operation: DependencyOperation::Remove,
+            scope: DependencyScope::Local,
+            workspace,
+            requested: specs,
+            removed,
+            summary: dependency_summary(before.as_ref(), after.as_ref(), 0),
+        },
+        || Ok(()),
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn rejects_an_empty_package_list() {
+        let result = run(Vec::new(), None, ScriptPolicy::Run).await;
+        assert!(result.is_err());
+    }
+}
diff --git a/crates/pm/src/cmd/update.rs b/crates/pm/src/commands/update.rs
similarity index 92%
rename from crates/pm/src/cmd/update.rs
rename to crates/pm/src/commands/update.rs
index 2f709df6a0..3e746ba60d 100644
--- a/crates/pm/src/cmd/update.rs
+++ b/crates/pm/src/commands/update.rs
@@ -1,9 +1,11 @@
+//! Dependency update command.
+
 use crate::service::update::clean_package_lock;
 use crate::util::cli_enum::{ReifyMode, ScriptPolicy};
 use crate::util::install_progress::DownloadBaseline;
 use crate::util::invocation;
 use crate::util::presenter::emit;
-use crate::{cmd::install::install_with_mode, helper::workspace::init_project_root};
+use crate::{commands::install::install_with_mode, helper::workspace::init_project_root};
 use anyhow::{Context, Result};
 use clap::Args;
 
@@ -18,7 +20,9 @@ pub struct UpdateArgs {
     pub force: bool,
 }
 
-pub async fn update(args: UpdateArgs, scripts: ScriptPolicy) -> Result<()> {
+pub use UpdateArgs as Options;
+
+pub async fn run(args: UpdateArgs, scripts: ScriptPolicy) -> Result<()> {
     let machine = invocation::json();
     let download_baseline = machine.then(DownloadBaseline::capture);
     let cwd = std::env::current_dir().context("Failed to get current directory")?;
diff --git a/crates/pm/src/cmd/view.rs b/crates/pm/src/commands/view.rs
similarity index 98%
rename from crates/pm/src/cmd/view.rs
rename to crates/pm/src/commands/view.rs
index 860941656a..111a2be2a9 100644
--- a/crates/pm/src/cmd/view.rs
+++ b/crates/pm/src/commands/view.rs
@@ -1,3 +1,5 @@
+//! Registry package-metadata command.
+
 use std::collections::{BTreeMap, HashMap};
 
 use anyhow::{Context as _, Result, anyhow};
@@ -15,7 +17,7 @@ use crate::util::presenter::emit;
 use crate::util::user_config::get_registry;
 
 /// View package information from registry, similar to npm view
-pub async fn view(package_spec: &str) -> Result<()> {
+pub async fn run(package_spec: &str) -> Result<()> {
     let registry_url = get_registry();
     view_with_registry(package_spec, &registry_url).await
 }
diff --git a/crates/pm/src/cmd/whoami.rs b/crates/pm/src/commands/whoami.rs
similarity index 95%
rename from crates/pm/src/cmd/whoami.rs
rename to crates/pm/src/commands/whoami.rs
index 9365bc02f7..63fbd739f9 100644
--- a/crates/pm/src/cmd/whoami.rs
+++ b/crates/pm/src/commands/whoami.rs
@@ -1,3 +1,5 @@
+//! Registry identity command.
+
 use anyhow::Result;
 
 use crate::error::{CliError, classify};
@@ -7,7 +9,7 @@ use crate::util::invocation;
 use crate::util::presenter::emit;
 use crate::util::user_config::get_registry;
 
-pub async fn whoami() -> Result<()> {
+pub async fn run() -> Result<()> {
     let registry = get_registry();
     let token = auth::require_token(&registry).await?;
 
diff --git a/crates/pm/src/helper/mod.rs b/crates/pm/src/helper/mod.rs
index b965ef7bba..4aa1a12f15 100644
--- a/crates/pm/src/helper/mod.rs
+++ b/crates/pm/src/helper/mod.rs
@@ -1,4 +1,4 @@
-//! Cross-cutting orchestration helpers between [`crate::cmd`]/[`crate::service`]
+//! Cross-cutting orchestration helpers between [`crate::commands`]/[`crate::service`]
 //! and the `utoo_ruborist` resolver — workspace topology, lockfile lifecycle,
 //! and dep-graph utilities that don't belong to a single service.
 //!
diff --git a/crates/pm/src/lib.rs b/crates/pm/src/lib.rs
new file mode 100644
index 0000000000..814b7f62ef
--- /dev/null
+++ b/crates/pm/src/lib.rs
@@ -0,0 +1,83 @@
+//! Embeddable API for the utoo package manager.
+//!
+//! The native `utoo` binary is a thin wrapper over [`run_cli`]. Hosts that
+//! want package-manager behavior in-process should call the modules under
+//! [`commands`] after configuring process-wide defaults through [`initialize`].
+
+mod cli;
+mod cli_entry;
+pub mod commands;
+mod constants;
+pub mod error;
+mod fs;
+mod helper;
+mod model;
+mod service;
+mod util;
+
+use std::path::PathBuf;
+
+use anyhow::Result;
+use clap::CommandFactory;
+
+/// utoo package-manager version.
+pub const VERSION: &str = constants::APP_VERSION;
+
+/// Build the complete clap command tree used by the native binary.
+pub fn command() -> clap::Command {
+    cli::Cli::command()
+}
+
+/// Public types used by command entry points.
+pub mod types {
+    pub use crate::cli::ConfigCommands;
+    pub use crate::helper::migrate::{FromPm, MigrateResult};
+    pub use crate::model::cli_output::*;
+    pub use crate::service::init::InitOutput;
+    pub use crate::service::script::{MissingScript, ScriptExit, ScriptOutput};
+    pub use crate::service::workspace::{WorkspaceFilter, WorkspaceJson};
+    pub use crate::util::cli_enum::{
+        ConfigScope, ConfirmationPolicy, InitMode, InstallScope, OmitType, PackageAction,
+        ProvenancePolicy, PublishAccess, ReifyMode, RunMode, SaveType, ScriptPolicy,
+    };
+    pub use clap_complete::Shell;
+}
+
+/// Process-wide defaults used by the command layer.
+///
+/// utoo currently stores these settings once per process. Call [`initialize`]
+/// before the first command when the host needs values other than the built-in
+/// defaults. Repeated initialization with different values is not supported.
+#[derive(Debug, Clone, Default)]
+pub struct InitializeOptions {
+    /// Registry URL override. Configuration and environment defaults are used
+    /// when omitted.
+    pub registry: Option<String>,
+    /// Package cache directory override.
+    pub cache_dir: Option<PathBuf>,
+    /// Whether peer dependencies should be skipped.
+    pub legacy_peer_deps: Option<bool>,
+    /// Maximum number of concurrent manifest requests.
+    pub manifests_concurrency_limit: Option<usize>,
+    /// Maximum number of concurrent lifecycle scripts.
+    pub script_concurrency_limit: Option<usize>,
+}
+
+/// Initialize process-wide package-manager defaults for embedded use.
+pub async fn initialize(options: InitializeOptions) -> Result<()> {
+    util::sysconf::init();
+    util::user_config::init_registry(options.registry).await?;
+    util::user_config::set_cache_dir(
+        options
+            .cache_dir
+            .map(|path| path.to_string_lossy().into_owned()),
+    )
+    .await;
+    util::user_config::set_legacy_peer_deps(options.legacy_peer_deps);
+    util::user_config::set_manifests_concurrency_limit(options.manifests_concurrency_limit);
+    util::user_config::set_script_concurrency_limit(options.script_concurrency_limit);
+    Ok(())
+}
+
+/// Run the full native command-line application.
+pub use cli_entry::run as run_cli;
diff --git a/crates/pm/src/main.rs b/crates/pm/src/main.rs
index 008906681d..322ffe34f9 100644
--- a/crates/pm/src/main.rs
+++ b/crates/pm/src/main.rs
@@ -1,636 +1,3 @@
-use std::{io, process};
-
-use anyhow::{Context, Result};
-use clap::error::ErrorKind as ClapErrorKind;
-use clap::{CommandFactory, FromArgMatches};
-
-use crate::cli::{Cli, Commands, detect_shell_from_env};
-use crate::cmd::clean::clean;
-use crate::cmd::list::list_dependencies;
-use crate::cmd::rebuild::rebuild;
-use crate::cmd::run::{run, run_fallback};
-use crate::cmd::update::update;
-use crate::cmd::view::view;
-use crate::constants::{APP_NAME, APP_VERSION};
-use crate::error::{CliError, ErrorKind, classify};
-use crate::helper::auto_update::init_auto_update;
-use crate::helper::self_pin::handoff_if_needed;
-use crate::model::cli_output::{
-    CompletionsResult, ErrorDetails, HelpResult, HelpTarget, InitResult, RequestedPackage,
-    RequiredBy, VersionResult,
-};
-use crate::service::config::ConfigService;
-use crate::service::script::{MissingScript, ScriptExit, script_failure_details};
-use crate::service::workspace::WorkspaceFilter;
-use crate::util::cli_enum::{
-    ColorPolicy, ConfigScope, ConfirmationPolicy, ConsoleVerbosity, InitMode, OutputFormat,
-    ProvenancePolicy, ScriptPolicy,
-};
-use crate::util::config_file::Config;
-use crate::util::format_print::{format_resolve_chain, resolve_chain};
-use crate::util::invocation::{self, Invocation};
-use crate::util::logger::{get_log_file_path, init_tracing, log_time, log_time_end};
-use crate::util::presenter;
-use crate::util::user_config::{
-    init_registry, set_cache_dir, set_legacy_peer_deps, set_manifests_concurrency_limit,
-    set_script_concurrency_limit,
-};
-
-mod cli;
-mod cmd;
-mod constants;
-mod error;
-mod fs;
-mod helper;
-mod model;
-mod service;
-mod util;
-
 fn main() {
-    invocation::start();
-    crate::util::sysconf::init();
-
-    let worker_threads = std::thread::available_parallelism()
-        .map(|n| n.get())
-        .unwrap_or(4);
-
-    let result = tokio::runtime::Builder::new_multi_thread()
-        .enable_all()
-        .worker_threads(worker_threads)
-        .build()
-        .expect("failed to build tokio runtime")
-        .block_on(async_main());
-
-    if let Err(e) = result {
-        let category = classify(&e);
-        // A failed package script propagates its own exit status so
-        // `utoo run <script>` mirrors the script: a non-zero `exit N` becomes
-        // N, and a signal death (e.g. SIGPIPE from `script | head`) becomes
-        // 128+N. JSON invocations always use the stable category code.
-        let exit_code = if invocation::json() {
-            category.exit_code() as i32
-        } else {
-            e.downcast_ref::<ScriptExit>()
-                .map_or_else(|| category.exit_code() as i32, |s| s.code)
-        };
-        if invocation::json() {
-            let cli_error = e.downcast_ref::<CliError>();
-            let message = cli_error.map_or_else(|| e.to_string(), |e| e.message().to_string());
-            let causes = e
-                .chain()
-                .skip(1)
-                .map(ToString::to_string)
-                .collect::<Vec<_>>();
-            let script_details = script_failure_details(&e);
-            let dependency_details = dependency_failure_details(&e);
-            let code = cli_error.map_or_else(
-                || {
-                    if script_details.is_some() {
-                        "script_failed"
-                    } else if dependency_details.is_some() {
-                        "dependency_resolution_failed"
-                    } else {
-                        "operation_failed"
-                    }
-                },
-                CliError::code,
-            );
-            let report = presenter::ErrorReport {
-                command: invocation::command(),
-                subcommand: invocation::subcommand(),
-                category,
-                code,
-                exit_code: category.exit_code(),
-                message: &message,
-                causes: &causes,
-                suggestion: cli_error.and_then(CliError::suggestion),
-                partial_result: cli_error.and_then(CliError::partial_result),
-                details: cli_error
-                    .and_then(CliError::details)
-                    .or(script_details.as_ref())
-                    .or(dependency_details.as_ref()),
-                log_path: get_log_file_path().map(|path| path.to_string_lossy().into_owned()),
-            };
-            let result = presenter::write_error(&mut io::stderr().lock(), &report);
-            if result.is_err() {
-                process::exit(exit_code);
-            }
-        } else if let Some(chain) = format_resolve_chain(&e) {
-            eprintln!("error: {e:#}\n\n{chain}");
-        } else {
-            eprintln!("error: {e:#}");
-        }
-        if !invocation::quiet()
-            && let Some(log_path) = get_log_file_path()
-        {
-            eprintln!("Full logs saved to: {}", log_path.display());
-        }
-        process::exit(exit_code);
-    }
-}
-
-async fn async_main() -> Result<()> {
-    let args: Vec<String> = std::env::args().collect();
-    let json_requested = has_flag_before_delimiter(&args, "--json");
-    let no_color_requested = has_flag_before_delimiter(&args, "--no-color");
-    let color = ColorPolicy::from(
-        json_requested || no_color_requested || std::env::var_os("NO_COLOR").is_some(),
-    );
-    color.apply();
-
-    // Preserve the custom root help catalog for human invocations. JSON help is
-    // handled through clap below so stdout remains one machine document.
-    if !json_requested && args.len() > 1 && (args[1] == "-h" || args[1] == "--help") {
-        let config = Config::load(ConfigScope::Local).await?;
-        let config_service = ConfigService::new(config);
-        config_service.print_help()?;
-        return Ok(());
-    }
-
-    log_time(); // Start global timer
-    let cli = match Cli::command()
-        .color(color.clap_choice())
-        .try_get_matches_from(&args)
-        .and_then(|matches| Cli::from_arg_matches(&matches))
-    {
-        Ok(cli) => cli,
-        Err(error) => {
-            if json_requested {
-                match error.kind() {
-                    ClapErrorKind::DisplayHelp | ClapErrorKind::DisplayVersion => {
-                        let command = if error.kind() == ClapErrorKind::DisplayVersion {
-                            "version"
-                        } else {
-                            "help"
-                        };
-                        if command == "version" {
-                            presenter::write(
-                                &mut io::stdout().lock(),
-                                command,
-                                None,
-                                &VersionResult {
-                                    version: APP_VERSION.to_string(),
-                                },
-                            )?;
-                        } else {
-                            presenter::write(
-                                &mut io::stdout().lock(),
-                                command,
-                                None,
-                                &HelpResult {
-                                    target: detect_help_target(&args),
-                                    text: error.to_string().trim_end().to_string(),
-                                },
-                            )?;
-                        }
-                        return Ok(());
-                    }
-                    _ => {
-                        let causes = Vec::new();
-                        presenter::write_error(
-                            &mut io::stderr().lock(),
-                            &presenter::ErrorReport {
-                                command: detect_command(&args),
-                                subcommand: detect_subcommand(&args),
-                                category: ErrorKind::Usage,
-                                code: "invalid_arguments",
-                                exit_code: ErrorKind::Usage.exit_code(),
-                                message: error.to_string().trim(),
-                                causes: &causes,
-                                suggestion: None,
-                                partial_result: None,
-                                details: None,
-                                log_path: None,
-                            },
-                        )?;
-                        process::exit(2);
-                    }
-                }
-            }
-            error.exit();
-        }
-    };
-    let color =
-        ColorPolicy::from(cli.json || cli.no_color || std::env::var_os("NO_COLOR").is_some());
-    color.apply();
-    let verbosity = ConsoleVerbosity::from_flags(cli.verbose, cli.quiet || cli.json);
-    let execute_version = matches!(
-        &cli.command,
-        Some(Commands::Execute { command, .. }) if matches!(command.as_str(), "--version" | "-v")
-    );
-    let command = if cli.version || execute_version {
-        Some("version")
-    } else {
-        cli.command
-            .as_ref()
-            .map(Commands::json_name)
-            .or_else(|| cli.script_name.as_ref().map(|_| "run"))
-            .or_else(|| (cli.command.is_none() && cli.script_name.is_none()).then_some("install"))
-    };
-    let subcommand = cli.command.as_ref().and_then(Commands::json_subcommand);
-    invocation::init(Invocation {
-        output: OutputFormat::from(cli.json),
-        verbosity,
-        color,
-        command,
-        subcommand,
-    });
-
-    // Handle version before the unsupported-command gate: `--json --version`
-    // is itself a machine-readable command result.
-    if cli.version || execute_version {
-        let output = VersionResult {
-            version: APP_VERSION.to_string(),
-        };
-        return presenter::emit("version", &output, || {
-            println!("{APP_VERSION}");
-            Ok(())
-        });
-    }
-
-    if cli.uses_project_package_manager() {
-        handoff_if_needed(
-            &std::env::current_dir()?,
-            &args[1..],
-            cli.registry.clone(),
-            cli.cache_dir.clone(),
-        )
-        .await?;
-    }
-
-    // Handle completions early to avoid unnecessary initialization (tracing, registry, auto-update)
-    if let Some(Commands::Completions { shell }) = cli.command {
-        let shell = shell.or_else(detect_shell_from_env);
-
-        let Some(shell) = shell else {
-            if invocation::json() {
-                return Err(CliError::usage(
-                    "could not detect shell; specify bash, zsh, fish, powershell, or elvish",
-                )
-                .into());
-            }
-            eprintln!(
-                "Could not detect shell. Usage: utoo completions <bash|zsh|fish|powershell|elvish>"
-            );
-            process::exit(2);
-        };
-
-        if invocation::json() {
-            let script = tokio::task::spawn_blocking(move || {
-                let mut output = Vec::new();
-                let mut cmd = Cli::command();
-                clap_complete::generate(shell, &mut cmd, APP_NAME, &mut output);
-                String::from_utf8(output).context("Generated completion script is not UTF-8")
-            })
-            .await
-            .context("Failed to generate shell completions")??;
-            return presenter::emit(
-                "completions",
-                &CompletionsResult {
-                    shell: shell.to_string(),
-                    script,
-                },
-                || Ok(()),
-            );
-        }
-
-        tokio::task::spawn_blocking(move || {
-            let mut cmd = Cli::command();
-            clap_complete::generate(shell, &mut cmd, APP_NAME, &mut std::io::stdout());
-        })
-        .await
-        .context("Failed to generate shell completions")?;
-
-        return Ok(());
-    }
-
-    if cli.json && matches!(&cli.command, Some(Commands::Login)) {
-        return Err(
-            CliError::usage("login requires an interactive browser flow")
-                .with_code("interactive_required")
-                .with_suggestion("run without `--json`")
-                .into(),
-        );
-    }
-
-    // Initialize tracing (replaces set_verbose)
-    let (log_file, _guard) =
-        init_tracing(verbosity, color).context("Failed to initialize logging")?;
-
-    tracing::debug!(
-        log_file = %log_file.display(),
-        ?verbosity,
-        "Logger initialized"
-    );
-
-    // Run --from migration early, before config is cached by init_registry
-    if let Some(Commands::Install(args)) = &cli.command {
-        cmd::install::migrate_from(args.from).await?;
-    }
-
-    // global registry
-    init_registry(cli.registry).await?;
-
-    // set cache directory
-    set_cache_dir(cli.cache_dir).await;
-
-    // set legacy_peer_deps when set --legacy
-    if cli.legacy_peer_deps == Some(true) {
-        set_legacy_peer_deps(cli.legacy_peer_deps);
-    }
-
-    // Concurrency limits — the setters ignore `None`, so passing the CLI option
-    // straight through applies an override only when one was given.
-    set_manifests_concurrency_limit(cli.manifests_concurrency_limit);
-    set_script_concurrency_limit(cli.script_concurrency_limit);
-
-    // Auto update: check cache → update or refresh in background
-    init_auto_update().await;
-
-    match cli.command {
-        Some(Commands::Clean { pattern, yes }) => {
-            let confirmation = ConfirmationPolicy::from(yes);
-            if confirmation.requires_interaction() && !invocation::interactive() {
-                return Err(CliError::usage(
-                    "refusing to prompt for cache deletion in non-interactive mode",
-                )
-                .with_suggestion("rerun with `utoo clean --yes`")
-                .into());
-            }
-            clean(&pattern, confirmation).await?;
-            log_time_end(&format!("{pattern} cleaned"));
-        }
-        Some(Commands::Install(args)) => {
-            cmd::install::run(args, cli.legacy_peer_deps).await?;
-        }
-        Some(Commands::Uninstall {
-            specs,
-            workspace,
-            ignore_scripts,
-        }) => {
-            cmd::install::uninstall(specs, workspace, ScriptPolicy::from(ignore_scripts)).await?;
-        }
-        Some(Commands::Rebuild) => {
-            let cwd = std::env::current_dir()?;
-            rebuild(&cwd).await?;
-            log_time_end("All packages rebuilt");
-        }
-        Some(Commands::Deps { workspace_only }) => {
-            cmd::deps::run(workspace_only).await?;
-        }
-        Some(Commands::Update(args)) => {
-            update(args, ScriptPolicy::Run).await?;
-            log_time_end("All packages updated");
-        }
-        Some(Commands::List { package }) => {
-            let cwd = std::env::current_dir()?;
-            list_dependencies(&cwd, &package).await?;
-        }
-        Some(Commands::Execute { command, args }) => {
-            service::execute::execute_package(&command, args).await?;
-        }
-        Some(Commands::Run {
-            script,
-            workspace,
-            workspaces,
-            if_present,
-            args,
-        }) => {
-            let missing = if if_present {
-                MissingScript::Skip
-            } else {
-                MissingScript::Fail
-            };
-            run(
-                script.as_deref(),
-                WorkspaceFilter::from_flags(workspace, workspaces),
-                missing,
-                (!args.is_empty()).then_some(args),
-            )
-            .await?;
-        }
-        Some(Commands::View { package }) => {
-            view(&package).await?;
-        }
-        Some(Commands::Link { packages, prefix }) => {
-            cmd::link::run(packages, prefix).await?;
-        }
-        Some(Commands::Init { yes }) => {
-            let mode = InitMode::from(yes);
-            if mode.requires_interaction() && !invocation::interactive() {
-                return Err(CliError::usage(
-                    "refusing to prompt for package metadata in non-interactive mode",
-                )
-                .with_suggestion("re-run with `utoo init --yes`")
-                .into());
-            }
-            let output = if invocation::json() {
-                service::init::InitOutput::Machine
-            } else {
-                service::init::InitOutput::Human
-            };
-            service::init::init(mode, output, None).await?;
-            log_time_end("package.json created");
-            if invocation::json() {
-                let path = std::env::current_dir()?.join("package.json");
-                let package: serde_json::Value =
-                    serde_json::from_str(&crate::fs::read_to_string(&path).await?)?;
-                presenter::emit(
-                    "init",
-                    &InitResult {
-                        path: path.to_string_lossy().into_owned(),
-                        name: package["name"].as_str().unwrap_or_default().to_string(),
-                        version: package["version"].as_str().unwrap_or_default().to_string(),
-                    },
-                    || Ok(()),
-                )?;
-            }
-        }
-        Some(Commands::Pack { path, dry_run }) => {
-            cmd::pm_pack::pack(path, dry_run.into()).await?;
-            log_time_end("Pack complete");
-        }
-        Some(Commands::Publish {
-            tag,
-            dry_run,
-            otp,
-            access,
-            // utoo performs no Git cleanliness checks, so `--no-git-checks` is a
-            // documented no-op accepted for pnpm/npm compatibility.
-            no_git_checks: _,
-            provenance,
-        }) => {
-            // `--workspace`/`--filter` selects member(s); empty means the current
-            // package. `--workspaces` is intentionally NOT honored here to avoid
-            // an accidental publish of every member.
-            let filter = if cli.workspace.is_empty() {
-                WorkspaceFilter::Current
-            } else {
-                WorkspaceFilter::Selected(cli.workspace)
-            };
-            cmd::publish::publish(
-                tag.as_deref(),
-                dry_run.into(),
-                otp.as_deref(),
-                access,
-                filter,
-                ProvenancePolicy::from(provenance),
-            )
-            .await?;
-        }
-        Some(Commands::Ping { registry }) => {
-            cmd::ping::ping(registry.as_deref()).await?;
-        }
-        Some(Commands::Login) => {
-            cmd::login::login().await?;
-        }
-        Some(Commands::Whoami) => {
-            cmd::whoami::whoami().await?;
-        }
-        Some(Commands::Logout) => {
-            cmd::logout::logout().await?;
-        }
-        Some(Commands::Config { command }) => {
-            cmd::config::run(command).await?;
-        }
-        None => match cli.script_name {
-            // A bare `utoo <name>`: custom command from config, else script
-            Some(script_name) => {
-                run_fallback(
-                    &script_name,
-                    WorkspaceFilter::from_flags(cli.workspace, cli.workspaces),
-                    cli.script_args,
-                )
-                .await?;
-            }
-            // Default to install if no arguments
-            None => cmd::install::install_cwd(ScriptPolicy::from(cli.ignore_scripts)).await?,
-        },
-        // Completions is handled early before initialization
-        Some(Commands::Completions { .. }) => unreachable!(),
-    }
-
-    Ok(())
-}
-
-fn has_flag_before_delimiter(args: &[String], flag: &str) -> bool {
-    args.iter()
-        .take_while(|arg| arg.as_str() != "--")
-        .any(|arg| arg == flag)
-}
-
-fn detect_help_target(args: &[String]) -> Option<HelpTarget> {
-    let command = detect_command(args)?;
-    (command != "help" && command != "version").then(|| HelpTarget {
-        command: command.to_string(),
-        subcommand: detect_subcommand(args).map(str::to_string),
-    })
-}
-
-fn detect_command(args: &[String]) -> Option<&'static str> {
-    detect_command_token(args).map(|(command, _)| command)
-}
-
-fn detect_command_token(args: &[String]) -> Option<(&'static str, usize)> {
-    let mut index = 1;
-    while index < args.len() {
-        let value = args[index].as_str();
-        if value == "--" {
-            return None;
-        }
-        if matches!(
-            value,
-            "--registry"
-                | "--cache-dir"
-                | "--manifests-concurrency-limit"
-                | "--script-concurrency-limit"
-                | "--workspace"
-                | "--filter"
-        ) {
-            index += 2;
-            continue;
-        }
-        if value.starts_with('-') {
-            index += 1;
-            continue;
-        }
-        let command = match value {
-            "i" | "add" | "install" => "install",
-            "un" | "uninstall" | "remove" | "rm" => "uninstall",
-            "rb" | "rebuild" => "rebuild",
-            "c" | "clean" => "clean",
-            "d" | "deps" => "deps",
-            "u" | "update" => "update",
-            "ls" | "list" => "list",
-            "r" | "run" => "run",
-            "x" | "execute" => "execute",
-            "v" | "view" | "info" | "show" => "view",
-            "ln" | "link" => "link",
-            "pk" | "pm-pack" => "pack",
-            "pub" | "publish" => "publish",
-            "pg" | "ping" => "ping",
-            "lg" | "login" => "login",
-            "who" | "whoami" => "whoami",
-            "lo" | "logout" => "logout",
-            "cfg" | "config" => "config",
-            "create" | "init" => "init",
-            "cmp" | "completions" => "completions",
-            _ => "run",
-        };
-        return Some((command, index));
-    }
-    None
-}
-
-fn detect_subcommand(args: &[String]) -> Option<&'static str> {
-    let (command, index) = detect_command_token(args)?;
-    if command != "config" {
-        return None;
-    }
-    let mut index = index + 1;
-    while index < args.len() {
-        let value = args[index].as_str();
-        if value == "--" {
-            return None;
-        }
-        if matches!(
-            value,
-            "--registry"
-                | "--cache-dir"
-                | "--manifests-concurrency-limit"
-                | "--script-concurrency-limit"
-        ) {
-            index += 2;
-            continue;
-        }
-        if value.starts_with('-') {
-            index += 1;
-            continue;
-        }
-        return match value {
-            "set" => Some("set"),
-            "get" => Some("get"),
-            "list" => Some("list"),
-            _ => None,
-        };
-    }
-    None
-}
-
-fn dependency_failure_details(error: &anyhow::Error) -> Option<ErrorDetails> {
-    let chain = resolve_chain(error)?;
-    let (requested, required_by) = chain.split_last()?;
-    Some(ErrorDetails::Dependency {
-        package: RequestedPackage {
-            name: requested.0.clone(),
-            spec: requested.1.clone(),
-        },
-        required_by: required_by
-            .iter()
-            .map(|(name, version)| RequiredBy {
-                name: (!name.is_empty()).then(|| name.clone()),
-                version: (!version.is_empty()).then(|| version.clone()),
-            })
-            .collect(),
-    })
+    utoo_pm::run_cli();
 }
diff --git a/crates/pm/src/service/install.rs b/crates/pm/src/service/install.rs
index caeb88148a..794a2d3cc6 100644
--- a/crates/pm/src/service/install.rs
+++ b/crates/pm/src/service/install.rs
@@ -5,7 +5,7 @@ use std::collections::{HashMap, HashSet};
 use std::path::Path;
 use std::time::Instant;
 
-use crate::cmd::deps::build_deps;
+use crate::commands::deps::build_deps;
 use crate::fs;
 use crate::helper::global_bin::{get_global_bin_dir, get_global_package_dir};
 use crate::helper::lock::{
diff --git a/crates/pm/src/service/mod.rs b/crates/pm/src/service/mod.rs
index 551780155d..ea1e0aae7b 100644
--- a/crates/pm/src/service/mod.rs
+++ b/crates/pm/src/service/mod.rs
@@ -1,6 +1,6 @@
 //! Business-logic layer — the work behind each CLI command.
 //!
-//! [`crate::cmd`] assembles args and calls in here; this layer orchestrates
+//! [`crate::commands`] assembles args and calls in here; this layer orchestrates
 //! [`crate::util`] (I/O, cache, linker, http) and `utoo_ruborist` (resolution).
 //!
 //! ```text
diff --git a/crates/pm/tests/library_api.rs b/crates/pm/tests/library_api.rs
new file mode 100644
index 0000000000..9b9a714096
--- /dev/null
+++ b/crates/pm/tests/library_api.rs
@@ -0,0 +1,40 @@
+use utoo_pm::{InitializeOptions, commands, types};
+
+/// Keep the embeddable surface wired to every business command dispatched by
+/// the native CLI. Merely naming each function from an external-crate test
+/// catches accidental visibility regressions without performing side effects.
+#[test]
+fn exposes_native_command_surface() {
+    let _ = utoo_pm::initialize;
+    let _ = InitializeOptions::default();
+    let _ = utoo_pm::command();
+    assert!(!utoo_pm::VERSION.is_empty());
+
+    let _ = commands::clean::run;
+    let _ = commands::install::run;
+    let _ = commands::install::project;
+    let _ = commands::install::current_project;
+    let _ = commands::install::global;
+    let _ = commands::uninstall::run;
+    let _ = commands::rebuild::run;
+    let _ = commands::deps::run;
+    let _ = commands::update::run;
+    let _ = commands::list::run;
+    let _ = commands::execute::run;
+    let _ = commands::run::run;
+    let _ = commands::view::run;
+    let _ = commands::link::run;
+    let _ = commands::init::run;
+    let _ = commands::pack::run;
+    let _ = commands::publish::run;
+    let _ = commands::ping::run;
+    let _ = commands::login::run;
+    let _ = commands::whoami::run;
+    let _ = commands::logout::run;
+    let _ = commands::config::run;
+    let _ = commands::completions::generate;
+
+    let _: Option<types::ScriptPolicy> = None;
+    let _: Option<types::WorkspaceFilter> = None;
+    let _: Option<types::ConfigCommands> = None;
+}