command-sdk.md

Command SDK

xfetch-command-api is the contract for CLI command addons. A command addon receives a JSON request with positional arguments and returns plain text; the core prints the text as-is unless the user asks for a layout.

Protocol

• Request: JSON on stdin for wasm core modules and component guests; native commands may also receive arguments as process arguments.
• Response: plain text on stdout, one field per line.
• Diagnostics: stderr only.
• Exit code: 0 on success; non-zero on failure.

{
  "version": 1,
  "kind": "command",
  "command": "github",
  "args": ["owner/repo"],
  "cwd": "/home/user/project",
  "env": {}
}

repo: owner/repo
author: owner
languages: C, JavaScript, PHP
stars: 1234

Rust Core Module

[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"
xfetch-command-api = "0.3"
xfetch-guest-api = "0.3"

use xfetch_command_api::{read_command_args_or_default, write_command_lines};

fn main() {
    let args = read_command_args_or_default().unwrap_or_default();
    let repo = args.first().map(String::as_str).unwrap_or("owner/repo");
    write_command_lines(&[format!("repo: {repo}")]).expect("write output");
}

Wasm core modules use the same JSON request as native commands. Host calls come from xfetch-guest-api and remain governed by the manifest allowlist.

Component Guest

Component guests implement the command world in wit/xfetch-runtime.wit:

world command {
    import host;
    export run: func(request: string) -> result<string, string>;
}

Parse the request string, use the typed host.fetch / host.exec imports as needed, and return the plain-text response. Returning an error string reports a command failure.

Native Command

Native command addons can read positional arguments from std::env::args().skip(1) and write text to stdout. The core also sends the JSON request on stdin, so a native command may use either form.

Output Conventions

• Prefer key: value lines for readability and future layout support.
• Keep ANSI escapes out unless the command explicitly opts into terminal output.
• Do not write logs to stdout; use stderr.
• Return an empty response only when the command has nothing to show.

Security

• Native commands run unsandboxed with the current user's privileges.
• Wasm commands use the manifest capability policy: HTTP, exec, filesystem, environment and args are deny-by-default.
• Command output is printed by the core; commands should not assume they own the terminal.