VT Code follows the [Command Line Interface Guidelines](https://clig.dev/) and standard UNIX principles to ensure a robust and pipe-friendly experience:

- **Output Streams**: Primary output (e.g., code from `ask`, events from `exec`) is sent to `stdout`. All logs, metadata, reasoning traces, and interaction prompts are sent to `stderr`. This allows you to safely pipe `vtcode` output to other tools.

```bash

# Only the generated code is saved to file; metadata remains on screen

vtcode ask "factorial function in rust" > factorial.rs

```

- **Standard Arguments**: Adheres to GNU/POSIX argument parsing standards using `clap`, supporting standard flags like `--help`, `--version`, and `--` separator for positional arguments.

The command-line interface is built on specific principles for robustness and interoperability:

1. **Strict Output Separation**: Data goes to `stdout`, diagnostics/logs go to `stderr`. This enables clean piping of machine-readable output.

2. **Standard Argument Parsing**: Uses `clap` for POSIX/GNU compliance, supporting standard flags and behavior.

3. **Command Isolation**: Each sub-command (`ask`, `exec`, `chat`) is handled by a dedicated module in `src/cli/`, sharing core logic via `vtcode-core`.

4. **Signal Handling**: Graceful handling of `SIGINT`/`SIGTERM` to ensure resource cleanup (e.g., restoring terminal state).

Because VT Code strictly separates data (`stdout`) from metadata/logging (`stderr`), you can pipe the output of commands like `ask` and `exec` directly.

vtcode ask "code for a fibonacci function" > fib.py

Use `vtcode exec --json` to get a pipeable stream of structured events.

exec` prints progress, summaries, and outcomes to **stderr**. `stdout` remains silent unless you request structured output (via `--json`), allowing you to safely pipe the output to other tools without pollution.

For quick questions or piping to other tools, use the `ask` command:

vtcode ask "Write a Python function to calculate Fibonacci numbers" > fib.py

**Note**: `vtcode ask` sends the raw response code/text to **stdout**, while sending metadata (provider info, reasoning traces) to **stderr**. This makes it perfect for shell scripting and piping.

quiet: false,

quiet: false,

config: &CoreAgentConfig,

prompt_arg: Option<String>,

options: AskCommandOptions,

) -> Result<()> {

let prompt = resolve_prompt(prompt_arg, config.quiet)?;

tokio::select! {

res = handle_ask_command_impl(config, &prompt, options) => res,

_ = tokio::signal::ctrl_c() => {

eprintln!("{}", style("\nCancelled by user.").yellow());

// Standard generic error (1) or specialized exit code logic would go here,

// but for now we bail which results in non-zero exit from main.

anyhow::bail!("Operation cancelled");

}

}

async fn handle_ask_command_impl(

if !wants_json && !config.quiet {

fn resolve_prompt(prompt_arg: Option<String>, quiet: bool) -> Result<String> {

match prompt_arg {

Some(p) if p != "-" => Ok(p),

maybe_dash => {

use std::io::{IsTerminal, Read, self};

let force_stdin = matches!(maybe_dash.as_deref(), Some("-"));

if io::stdin().is_terminal() && !force_stdin {

anyhow::bail!(

"No prompt provided. Pass a prompt argument, pipe input, or use '-' to read from stdin."

);

}

if !force_stdin && !quiet {

eprintln!("Reading prompt from stdin...");

}

let mut buffer = String::with_capacity(1024);

io::stdin()

.read_to_string(&mut buffer)

.context("Failed to read prompt from stdin")?;

if buffer.trim().is_empty() {

anyhow::bail!("No prompt provided via stdin.");

}

Ok(buffer)

}

}

fn resolve_prompt(prompt_arg: Option<String>, quiet: bool) -> Result<String> {

if !force_stdin && !quiet {

tokio::select! {

res = handle_exec_command_impl(config, vt_cfg, options, prompt_arg) => res,

_ = tokio::signal::ctrl_c() => {

eprintln!("{}", style("\nCancelled by user.").yellow());

bail!("Operation cancelled");

}

}

async fn handle_exec_command_impl(

config: &CoreAgentConfig,

vt_cfg: &VTCodeConfig,

options: ExecCommandOptions,

prompt_arg: Option<String>,

) -> Result<()> {

let prompt = resolve_prompt(prompt_arg, config.quiet)?;

if !options.json && !config.quiet {

quiet: false,

async fn main() -> std::process::ExitCode {

match run().await {

Ok(_) => std::process::ExitCode::SUCCESS,

Err(err) => {

eprintln!("vtcode: error: {:#}", err);

std::process::ExitCode::FAILURE

}

panic_hook::init_panic_hook();

// Load .env (non-fatal if missing)

if let Err(err) = load_dotenv() {

if !args.quiet {

eprintln!("vtcode: warning: failed to load .env: {err}");

}

}

process_hardening::apply_process_hardening()

.context("failed to apply process hardening safeguards")?;

if !args.quiet {

eprintln!("vtcode: warning: failed to initialize tracing from environment: {err}");

}

if !args.quiet {

eprintln!("vtcode: warning: failed to initialize tracing from config: {err}");

}

cli::handle_ask_single_command(core_cfg, Some(prompt), cli::AskCommandOptions::default())

cli::handle_ask_single_command(core_cfg, Some(prompt), cli::AskCommandOptions::default())

cli::handle_ask_single_command(core_cfg, prompt.clone(), options).await?;