Skip to content

Ask Command

The ask command allows you to query the LLM model directly with questions and get informative responses.

Usage

agent ask [flags] <question>

Your question can be multiple words, and will be sent as-is to the model. The response will be formatted as markdown by default.

Examples

# Basic question
agent ask "What is a file descriptor in Linux?"

# Using a specific provider and model
agent ask --provider openai --model gpt-4o-mini "How do I check disk usage on Linux?"

# Get the output as plain text (no markdown formatting)
agent ask --plain "Explain how pipes work in bash"

# Stream the response (see output as it's generated)
agent ask --stream "What are the benefits of using Go for CLI applications?"

# Disable web search for a quicker, offline answer
agent ask --websearch=false "Explain the CAP theorem"

# Include file context
agent ask --context README.md "Summarize the setup steps"

# Include latest terminal context (requires bash-reader plugin)
agent ask "why the command failed" --use-terminal-context 3

# Shortcuts for terminal context depth
agent ask "why did this fail" -1
agent ask "what happened here" -5

Flags

Flag Short Default Description
--provider -p From config The LLM provider to use
--model -m From config The model ID to use
--print -x true Whether to print the response to stdout
--log -l false Whether to log the input and output to a file
--stream -s false Stream the response to the stdout as it's generated
--plain -k false Render the response as plain text (no markdown)
--memory -M false Include memory entries in the system prompt
--websearch -w From config (true) Allow the answer to use web search; pass --websearch=false for quicker answers
--context -c [] Include file content as context (repeatable)
--use-terminal-context 0 (off) Include latest N terminal entries as context; N must be 1-5 (requires bash-reader plugin)
--terminal-context-1 -1 false Shortcut for --use-terminal-context 1
--terminal-context-2 -2 false Shortcut for --use-terminal-context 2
--terminal-context-3 -3 false Shortcut for --use-terminal-context 3
--terminal-context-4 -4 false Shortcut for --use-terminal-context 4
--terminal-context-5 -5 false Shortcut for --use-terminal-context 5

Terminal Context

The --use-terminal-context <N> flag prepends terminal entries to your question inside a <context> block.

It reads the latest N entries (where N is 1..5) captured by bash-reader from:

  • $HOME/.local/share/terminal-agent/terminal-context/index.log

Captured fields include:

  • Command text
  • Exit code
  • Output when available (safe mode may provide command and exit code only)

This requires the bash-reader plugin:

agent plugin install bash-reader

If the plugin is not installed, agent ask --use-terminal-context ... fails with an install hint.

Notes:

  • --use-terminal-context requires an explicit numeric argument (1..5)
  • Use only one shortcut flag at a time (-1 to -5)
  • Do not combine --use-terminal-context with -1..-5 in one command

For storage details and uninstall options, see Plugin Command.

Streaming Output

When using the --stream flag, you'll see the output appear gradually as it's generated by the model, rather than waiting for the complete response. This provides a more interactive experience:

agent ask --stream "How does Docker containerization work?"

By default, ask may use the built-in websearch tool to pull in up-to-date information from the internet before answering. The model decides whether a given question needs a search; questions it can answer from its own knowledge are answered directly.

Web search activates only when all of the following hold:

  • It is enabled (the default; configurable with web_search in config or the --websearch flag).
  • The TAVILY_KEY environment variable is set (the websearch tool requires it).
  • The selected provider supports tool calling (the local llama provider does not).

When any of these is not met, ask answers in a single shot without searching, so there is no error or slowdown if web search is unavailable.

Use --websearch=false when you want the quickest possible answer and do not need fresh information:

agent ask --websearch=false "What is a mutex?"

To turn web search off for every ask by default, set "web_search": false in ~/.config/terminal-agent/config.json.

Logging

If you use the --log flag, your question and the response will be saved to the history log:

agent ask --log "What are the differences between threads and processes?"

You can later query your history with the history command.