atuinsh/atuin · error

expected `atuin hook <agent>` or `atuin hook install <agent>

Error message

expected `atuin hook <agent>` or `atuin hook install <agent>`

What it means

`atuin hook` supports two forms: an action (`install <agent>`) or a bare agent name to emit hook output for that agent. Invoking it with neither fails immediately with usage guidance. It is a CLI argument validation error, not a runtime failure.

Source

Thrown at crates/atuin/src/command/client/hook.rs:167

#[derive(Parser, Debug)]
#[command(infer_subcommands = true, args_conflicts_with_subcommands = true)]
pub struct Cmd {
    #[command(subcommand)]
    action: Option<Action>,

    /// Which agent's hook format to parse (e.g., "claude-code")
    #[arg(value_name = "AGENT", hide = true)]
    agent: Option<String>,
}

impl Cmd {
    #[instrument(level = "trace", skip_all, err)]
    pub async fn run(self, settings: &Settings) -> Result<()> {
        match (self.action, self.agent) {
            (Some(Action::Install { agent }), None) => install(&agent),
            (None, Some(agent)) => handle(&agent, settings).await,
            (None, None) => {
                bail!("expected `atuin hook <agent>` or `atuin hook install <agent>`");
            }
            (Some(_), Some(_)) => {
                bail!("hook action cannot be combined with a positional agent");
            }
        }
    }
}

fn id_file_path(tool_use_id: &str) -> PathBuf {
    std::env::temp_dir().join(format!("atuin-hook-{tool_use_id}"))
}

async fn handle(agent_name: &str, settings: &Settings) -> Result<()> {
    let agent = Agent::from_name(agent_name)?;

    if let InstallKind::Extension { reload_hint, .. } = agent.install_kind() {
        bail!(
            "`atuin hook {agent_name}` is not supported. Use `atuin hook install {agent_name}`. \

View on GitHub (pinned to c0c717ab04)

Solutions

1. Pass the agent: `atuin hook <agent>` (e.g. atuin hook claude)
2. Or install hooks: `atuin hook install <agent>`
3. Run `atuin hook --help` to see valid forms

Example fix

// before
atuin hook
// after
atuin hook claude

# guard in scripts
[ -n "$AGENT" ] || { echo "usage: atuin hook <agent> | atuin hook install <agent>"; exit 2; }
atuin hook "$AGENT"

When it happens

Trigger: Running `atuin hook` with no subcommand and no positional agent argument.

Common situations: Typos such as running `atuin hook` alone; scripting the command without arguments; misunderstanding the two invocation forms.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

• hook action cannot be combined with a positional agent
• `atuin hook {agent_name}` is not supported. Use `atuin hook
• Failed to read from input
• authentication canceled
• You are not logged in

AI-assisted analysis of atuinsh/atuin@c0c717ab04 (2026-09-12). Data as JSON: /api/errors/4b1f01d9a6592385. Report an issue: GitHub.