Class: Kward::CLI

Inherits:

Object

• Object
• Kward::CLI

Includes:

CLI::AuthCommands, CLI::Commands, CLI::CompactionCommands, CLI::Doctor, CLI::GitCommands, CLI::HookCommands, CLI::InteractiveTurn, CLI::MemoryCommands, CLI::OpenRouterCommands, CLI::Plugins, CLI::ProjectSkills, CLI::ProjectSkillsCommands, CLI::PromptInterfaceSupport, CLI::Rendering, CLI::RuntimeHelpers, CLI::Sessions, CLI::Settings, CLI::SlashCommands, CLI::Stats, CLI::Sysprompt, CLI::Tabs, CLI::ToolSummaries, CLI::Transports, CLI::Worktrees

Defined in:

lib/kward/cli.rb,
lib/kward/cli/git.rb,
lib/kward/cli/tabs.rb,
lib/kward/cli/stats.rb,
lib/kward/cli/doctor.rb,
lib/kward/cli/plugins.rb,
lib/kward/cli/commands.rb,
lib/kward/cli/sessions.rb,
lib/kward/cli/settings.rb,
lib/kward/cli/rendering.rb,
lib/kward/cli/sysprompt.rb,
lib/kward/cli/worktrees.rb,
lib/kward/cli/compaction.rb,
lib/kward/cli/transports.rb,
lib/kward/cli/auth_commands.rb,
lib/kward/cli/hook_commands.rb,
lib/kward/cli/project_skills.rb,
lib/kward/cli/settings/menus.rb,
lib/kward/cli/settings/model.rb,
lib/kward/cli/slash_commands.rb,
lib/kward/cli/tool_summaries.rb,
lib/kward/cli/memory_commands.rb,
lib/kward/cli/runtime_helpers.rb,
lib/kward/cli/interactive_turn.rb,
lib/kward/cli/prompt_interface.rb,
lib/kward/cli/openrouter_commands.rb,
lib/kward/cli/project_skills_commands.rb

Overview

Command-line frontend that coordinates terminal interaction, sessions, tools, and model turns.

Defined Under Namespace

Modules: AuthCommands, Commands, CompactionCommands, Doctor, GitCommands, HookCommands, InteractiveTurn, MemoryCommands, OpenRouterCommands, Plugins, ProjectSkills, ProjectSkillsCommands, PromptInterfaceSupport, Rendering, RuntimeHelpers, Sessions, Settings, SlashCommands, Stats, Sysprompt, Tabs, ToolSummaries, Transports, Worktrees

Constant Summary

RESTORED_TOOL_OUTPUT_LIMIT =

2_000

INTERACTIVE_TOOL_OUTPUT_LINE_LIMIT =

10

STREAM_RENDER_INTERVAL =

0.025

INTERACTIVE_EVENT_DRAIN_LIMIT =

12

BUILTIN_SLASH_COMMANDS =

PromptCommands::BUILTIN_COMMANDS

BUILTIN_SLASH_COMMAND_NAMES =

PromptCommands::BUILTIN_RESERVED_COMMAND_NAMES

Instance Method Summary

• #apply_filter_system_prompt(conversation) ⇒ Object
• #authentication_error_message(error) ⇒ Object
• #config_error_message(error) ⇒ Object
• #debug_errors? ⇒ Boolean
• #dispatch ⇒ Object
• #edit_file_command(path) ⇒ Object
• #ensure_client! ⇒ Object
• #filter_prompt(instruction:, input:) ⇒ Object
• #filter_system_prompt ⇒ Object
• #initialize(argv: ARGV, stdin: STDIN, prompt: TTY::Prompt.new, client: nil, session_store: nil, context_usage: ContextUsage.new) ⇒ CLI constructor

  A new instance of CLI.

• #interactive_loop(agent: nil) ⇒ Object
• #one_shot(input, filter: false) ⇒ Object
• #piped_prompt ⇒ Object
• #read_stdin_input ⇒ Object
• #resolved_execution_mode(first_prompt:, stdin_input:) ⇒ Object
• #run ⇒ void

  Dispatches command-line modes, including RPC, login, stats export, Pan mode, one-shot prompts, and interactive chat.

• #run_prompt_or_interactive ⇒ Object
• #runtime_error_message(error) ⇒ Object

Constructor Details

#initialize(argv: ARGV, stdin: STDIN, prompt: TTY::Prompt.new, client: nil, session_store: nil, context_usage: ContextUsage.new) ⇒ CLI

Returns a new instance of CLI.

# File 'lib/kward/cli.rb', line 124

def initialize(argv: ARGV, stdin: STDIN, prompt: TTY::Prompt.new, client: nil, session_store: nil, context_usage: ContextUsage.new)
  @argv = argv
  @stdin = stdin
  @prompt = prompt
  @client = client
  @session_store = session_store
  @context_usage = context_usage
  @active_session = nil
  @session_diff = SessionDiff.new
  @cleanup_sessions = []
  @plugin_registry = nil
  @working_directory = nil
  @prompt_delimited = false
  @requested_mode = "auto"
  @startup_option_name = nil
  @skip_config = false
  @pending_reasoning_config = nil
  @pending_reasoning_config_mutex = Mutex.new
  @color_enabled = ANSI.enabled?($stdout)
end

Instance Method Details

#apply_filter_system_prompt(conversation) ⇒ Object

# File 'lib/kward/cli.rb', line 488

def apply_filter_system_prompt(conversation)
  return unless conversation.system_message

  conversation.system_message[:content] = [conversation.system_message[:content], filter_system_prompt].compact.join("\n\n")
end

#authentication_error_message(error) ⇒ Object

# File 'lib/kward/cli.rb', line 204

def authentication_error_message(error)
  <<~MESSAGE.rstrip
    Authentication required

    #{error.message}

    Run `kward doctor` to inspect your setup.
  MESSAGE
end

#config_error_message(error) ⇒ Object

# File 'lib/kward/cli.rb', line 184

def config_error_message(error)
  <<~MESSAGE.rstrip
    Invalid Kward config #{error.format}.

    File:
      #{error.path}

    Parser error:
      #{error.detail}

    Kward cannot safely continue with this config.

    Repair it with:
      kward edit #{error.path}

    Emergency fallback:
      kward --skip-config doctor
  MESSAGE
end

#debug_errors? ⇒ Boolean

Returns:

• (Boolean)

# File 'lib/kward/cli.rb', line 224

def debug_errors?
  ENV["KWARD_DEBUG"] == "1"
end

#dispatch ⇒ Object

Raises:

• (ArgumentError)

# File 'lib/kward/cli.rb', line 228

def dispatch
  if @startup_option_name
    discover_plugin_registry.run_startup_option(@startup_option_name)
    return
  end

  if @prompt_delimited
    ConfigFiles.ensure_default_config!
    run_prompt_or_interactive
    return
  end

  if help_command?
    print_command_help(@argv[1])
    return
  end
  raise ArgumentError, command_usage("help") if ["help", "--help", "-h"].include?(@argv.first)

  if version_command?
    print_version
    return
  end
  raise ArgumentError, command_usage("version") if ["version", "--version", "-v"].include?(@argv.first)

  ConfigFiles.ensure_default_config!

  if @argv.first == "init"
    if help_option_arguments?(@argv[1..] || [])
      print_command_help("init")
      return
    end
    raise ArgumentError, command_usage("init") unless @argv.length == 1

    install_starter_pack
    return
  end

  if @argv.first == "auth"
    handle_auth_command(@argv[1..] || [])
    return
  end

  if @argv.first == "doctor"
    if help_option_arguments?(@argv[1..] || [])
      print_command_help("doctor")
      return
    end
    raise ArgumentError, command_usage("doctor") unless @argv.length == 1

    ensure_client!
    exit 1 unless print_doctor
    return
  end

  if @argv.first == "hooks"
    if help_option_arguments?(@argv[1..] || [])
      print_command_help("hooks")
      return
    end

    handle_hooks_command((@argv[1..] || []).join(" "), command_line: true)
    return
  end

  if @argv.first == "skills"
    if help_option_arguments?(@argv[1..] || [])
      print_command_help("skills")
      return
    end

    handle_project_skills_cli_command(@argv[1..] || [])
    return
  end

  if @argv.first == "edit"
    if help_option_arguments?(@argv[1..] || [])
      print_command_help("edit")
      return
    end
    raise ArgumentError, command_usage("edit") unless @argv.length == 2

    edit_file_command(@argv[1])
    return
  end

  if @argv.first == "sysprompt"
    if help_option_arguments?(@argv[1..] || [])
      print_command_help("sysprompt")
      return
    end

    ensure_client!
    print_sysprompt(@argv[1..] || [])
    return
  end

  if @argv.first == "transport"
    if help_option_arguments?(@argv[1..] || [])
      print_command_help("transport")
      return
    end

    handle_transport_command(@argv[1..] || [])
    return
  end

  if @argv.first == "rpc"
    if help_option_arguments?(@argv[1..] || [])
      print_command_help("rpc")
      return
    end
    raise ArgumentError, command_usage("rpc") unless @argv.length == 1

    ensure_client!
    Kward::RPC::Server.new(input: @stdin, output: $stdout, client: @client).run
    return
  end

  if @argv.first == "stats"
    if @argv[1] == "tokens" && help_option_arguments?(@argv[2..] || [])
      print_command_help("stats")
      return
    end
    raise ArgumentError, command_usage("stats") unless @argv[1] == "tokens"

    export_token_stats(@argv[2..] || [])
    return
  end

  if @argv.first == "openrouter"
    if help_option_arguments?(@argv[1..] || [])
      print_command_help("openrouter")
      return
    end

    ensure_client!
    handle_openrouter_command(@argv[1..] || [])
    return
  end

  if pan_mode?
    if help_option_arguments?(@argv[1..] || [])
      print_command_help("pan")
      return
    end
    raise ArgumentError, command_usage("pan") unless @argv.length == 1

    ensure_client!
    PanServer.new(client: @client, working_directory: current_workspace_root).run
    return
  end

  if ["login", "--login"].include?(@argv.first)
    if help_option_arguments?(@argv[1..] || [])
      print_command_help("login")
      return
    end
    raise ArgumentError, command_usage("login") unless @argv.length <= 2

    login(provider: @argv[1])
    return
  end

  run_prompt_or_interactive
end

#edit_file_command(path) ⇒ Object

# File 'lib/kward/cli.rb', line 394

def edit_file_command(path)
  setup_interactive_prompt
  unless @prompt.respond_to?(:edit_file)
    raise ArgumentError, "The integrated editor requires an interactive terminal."
  end

  @prompt.edit_file(path, base_dir: Dir.pwd, allow_new: true)
ensure
  @prompt.close if @prompt.respond_to?(:close) && prompt_interface?
  clear_interactive_warning_sink if respond_to?(:clear_interactive_warning_sink, true)
end

#ensure_client! ⇒ Object

# File 'lib/kward/cli.rb', line 180

def ensure_client!
  @client ||= Client.new
end

#filter_prompt(instruction:, input:) ⇒ Object

# File 'lib/kward/cli.rb', line 478

def filter_prompt(instruction:, input:)
  <<~PROMPT
    Instruction:
    #{instruction}

    Input:
    #{input}
  PROMPT
end

#filter_system_prompt ⇒ Object

# File 'lib/kward/cli.rb', line 494

def filter_system_prompt
  <<~PROMPT.strip
    You are being used as a command-line text filter.

    Transform the provided input according to the user's instruction.
    Return only the transformed output.

    Do not include explanations, introductions, summaries, Markdown fences, or commentary.
    Do not say what you changed.
    Preserve the input format unless the instruction requires changing it.
    If the input is code, data, markup, or configuration, output only the resulting code/data/markup/configuration.
  PROMPT
end

#interactive_loop(agent: nil) ⇒ Object

# File 'lib/kward/cli.rb', line 508

def interactive_loop(agent: nil)
  setup_interactive_prompt(defer_warnings: true)
  prepare_interactive_project_skills
  session_store = interactive_session_store(agent)
  @resumed_last_session = false
  if session_store && @prompt.respond_to?(:update_tabs)
    agent = setup_interactive_tabs(session_store, agent)
  elsif session_store && agent.nil?
    agent = resume_last_session(session_store) || build_new_session_agent(session_store)
  elsif session_store
    @active_session = track_session(session_store.create(provider: current_model_provider, model: current_model_id, reasoning_effort: current_reasoning_effort))
    reset_session_diff
    @active_session.attach(agent.conversation)
  else
    agent ||= build_interactive_agent(new_conversation)
  end

  update_assistant_prompt(agent.conversation)
  @footer_conversation = agent.conversation

  print_visual_banner unless @resumed_last_session || @restored_tabs
  render_resumed_last_session_transcript(agent.conversation) if @resumed_last_session
  enable_interactive_warnings if respond_to?(:enable_interactive_warnings, true)

  @pending_inputs = []
  install_bang_completion_provider(agent)

  loop do
    service_background_tab_runs if respond_to?(:service_background_tab_runs, true)
    if @pending_inputs.empty? && active_tab&.shell && !active_tab.local_busy?
      run_kwsh_loop(active_tab.shell, tab: active_tab, history: build_kwsh_history(active_tab.agent))
    end
    input = @pending_inputs.shift || (active_tab ? poll_active_tab_input : @prompt.ask("You>"))
    if input.is_a?(Hash) && input[:editor_prompt]
      pending_inputs = run_editor_prompt_turn(input[:editor_prompt], active_tab&.agent || agent)
      pending_inputs.reverse_each { |pending_input| @pending_inputs.unshift(pending_input) }
      next
    end
    if input.is_a?(Hash) && input[:tab_action]
      tab_result = handle_tab_action(input, session_store)
      break if tab_result == PromptInterface::EXIT_INPUT
      agent = active_tab.agent if active_tab&.agent
      next
    end
    if input.is_a?(Hash) && input[:reasoning_action]
      next if active_tab && plugin_tab?

      conversation = active_tab ? active_tab.agent.conversation : agent.conversation
      cycle_reasoning(conversation, direction: input[:reasoning_action], persist: :debounced)
      agent = active_tab.agent if active_tab&.agent
      next
    end
    next if input == :tab_idle
    break if input.nil?

    display_input = submitted_display_input(input)
    command_input = display_input.nil? ? input : display_input
    command = command_input.strip
    next if command.empty? && input.strip.empty?
    if command.empty?
      handled = false
    else
      selected_input = selected_slash_command_input(command_input)
      if selected_input
        input = selected_input
        command = input.strip
        display_input = input if display_input
      end
      break if ["/exit", "/quit"].include?(command)
      if active_tab && plugin_tab? && command.start_with?("/")
        unless plugin_tab_command_allowed?(command)
          runtime_output("#{command.split.first} is unavailable in this plugin tab.")
          next
        end
        if active_tab.driver.respond_to?(:handle_command) && active_tab.driver.handles_command?(command)
          output = active_tab.driver.handle_command(command)
          runtime_output(output) unless output.to_s.empty?
          next
        end
      end
      handled, replacement_agent = handle_local_slash_command(command, agent, session_store)
      if replacement_agent?(replacement_agent)
        agent = active_tab ? replace_active_tab_agent(replacement_agent) : replacement_agent
      elsif active_tab&.agent
        agent = active_tab.agent
      end
    end
    next if handled
    if shell_command_input?(command_input)
      shell_result = handle_interactive_shell_command(command_input, agent)
      next if shell_result == true || shell_result == :tab_action
    end

    flush_pending_reasoning_config(conversation: active_tab.agent.conversation) if active_tab&.agent
    flush_pending_reasoning_config(conversation: agent.conversation) unless active_tab
    expanded_input = expand_prompt_template(input)
    display_input = display_input || input if expanded_input
    input = expanded_input || input
    @footer_conversation = active_tab.agent.conversation if active_tab&.agent
    @footer_conversation = agent.conversation unless active_tab
    begin
      @rewind_return_leaf_id = nil
      auto_name_active_session(display_input || input) unless active_tab && plugin_tab?
      if active_tab
        submit_tab_input(active_tab, input, display_input: display_input)
        pending_inputs = []
      else
        pending_inputs = run_interactive_turn(agent, input, display_input: display_input)
        agent = @busy_replacement_agent if replacement_agent?(@busy_replacement_agent)
        @busy_replacement_agent = nil
      end
      pending_inputs.reverse_each { |pending_input| @pending_inputs.unshift(pending_input) }
    rescue StandardError => e
      runtime_output("Error: #{e.message}")
    end
  end

  flush_pending_reasoning_config(conversation: active_tab.agent.conversation) if active_tab&.agent
  flush_pending_reasoning_config(conversation: agent.conversation) unless active_tab
  active_tab&.agent&.conversation || agent.conversation
rescue Interrupt
  flush_pending_reasoning_config(conversation: active_tab.agent.conversation) if active_tab&.agent
  flush_pending_reasoning_config(conversation: agent&.conversation) unless active_tab
  runtime_output("Goodbye.")
  active_tab&.agent&.conversation || agent&.conversation
ensure
  clear_bang_completion_provider
  begin
    stop_tabs if respond_to?(:stop_tabs, true)
    @prompt.close if prompt_interface?
  ensure
    clear_interactive_warning_sink if respond_to?(:clear_interactive_warning_sink, true)
    cleanup_unused_sessions
    remember_active_session(session_store)
  end
end

#one_shot(input, filter: false) ⇒ Object

# File 'lib/kward/cli.rb', line 426

def one_shot(input, filter: false)
  streamed = false
  assistant_streamed = false
  markdown_chunks = []
  conversation = new_conversation
  apply_filter_system_prompt(conversation) if filter
  hook_manager = lifecycle_hook_manager(conversation)
  hook_context = lifecycle_hook_context(conversation)
  agent = Agent.new(
    client: @client,
    tool_registry: ToolRegistry.new(
      workspace: configured_workspace,
      prompt: @prompt,
      plugin_tools: plugin_registry.tools,
      hook_manager: hook_manager,
      hook_context: hook_context
    ),
    conversation: conversation,
    hook_manager: hook_manager,
    hook_context: hook_context
  )
  summary = nil
  answer = if filter
    agent.ask(input)
  else
    agent.ask(input) do |event|
      summary = event.summary if event.is_a?(Events::TurnSummary)
      result = render_blocking_turn_event(event, markdown_chunks)
      streamed = true if result
      assistant_streamed = true if result == :assistant_streamed
    end
  end
  flush_markdown_deltas(markdown_chunks) if streamed
  return answer if filter

  text = assistant_streamed ? "" : render_markdown_transcript(answer)
  stats = turn_summary_text(summary)
  [text, stats.empty? ? nil : colored(stats, :metadata)].compact.reject(&:empty?).join("\n\n")
rescue StandardError
  flush_markdown_deltas(markdown_chunks) unless filter
  print_turn_summary(summary) unless filter
  raise
end

#piped_prompt ⇒ Object

# File 'lib/kward/cli.rb', line 645

def piped_prompt
  read_stdin_input.to_s.strip
end

#read_stdin_input ⇒ Object

# File 'lib/kward/cli.rb', line 649

def read_stdin_input
  return nil if @stdin.tty?

  @stdin.read
end

#resolved_execution_mode(first_prompt:, stdin_input:) ⇒ Object

# File 'lib/kward/cli.rb', line 470

def resolved_execution_mode(first_prompt:, stdin_input:)
  return @requested_mode unless @requested_mode == "auto"
  return "chat" if stdin_input.nil? && first_prompt.nil?
  return "filter" if !stdin_input.nil? && first_prompt

  "oneshot"
end

#run ⇒ void

This method returns an undefined value.

Dispatches command-line modes, including RPC, login, stats export, Pan mode, one-shot prompts, and interactive chat.

# File 'lib/kward/cli.rb', line 149

def run
  @argv = extract_global_options(@argv)
  if @startup_option_name && (!@argv.empty? || @prompt_delimited)
    raise ArgumentError, "Plugin startup option #{@startup_option_name} cannot be combined with a prompt or --"
  end
  ConfigFiles.skip_config = @skip_config
  ConfigFiles.ignore_local_instructions = @ignore_local_instructions
  with_working_directory { dispatch }
rescue ConfigFiles::ConfigError => e
  warn config_error_message(e)
  exit 1
rescue ArgumentError => e
  warn e.message
  warn "Run `kward help` for available commands."
  exit 1
rescue Client::AuthenticationError => e
  raise if debug_errors?

  warn authentication_error_message(e)
  exit 1
rescue StandardError => e
  raise if debug_errors?

  warn runtime_error_message(e)
  exit 1
ensure
  shutdown_plugins if respond_to?(:shutdown_plugins, true)
  ConfigFiles.skip_config = false
  ConfigFiles.ignore_local_instructions = false
end

#run_prompt_or_interactive ⇒ Object

# File 'lib/kward/cli.rb', line 406

def run_prompt_or_interactive
  ensure_client!
  stdin_input = read_stdin_input
  first_prompt = one_shot_prompt_argument

  case resolved_execution_mode(first_prompt: first_prompt, stdin_input: stdin_input)
  when "chat"
    interactive_loop
  when "filter"
    raise ArgumentError, "Filter mode requires stdin input." if stdin_input.nil?

    answer = one_shot(filter_prompt(instruction: first_prompt, input: stdin_input), filter: true)
    puts answer unless answer.empty?
  when "oneshot"
    input = first_prompt || stdin_input.to_s.strip
    answer = one_shot(input)
    puts answer unless answer.empty?
  end
end

#runtime_error_message(error) ⇒ Object

# File 'lib/kward/cli.rb', line 214

def runtime_error_message(error)
  <<~MESSAGE.rstrip
    Kward could not complete the request.

    #{error.message}

    Set KWARD_DEBUG=1 to show a backtrace.
  MESSAGE
end