onetool direct¶

Run tools from the shell, manage the execution server, or launch the interactive REPL.

onetool direct [OPTIONS] COMMAND [ARGS]...

onetool direct run¶

Execute a tool command from the shell.

onetool direct run [OPTIONS] [COMMAND]

Arguments:

COMMAND — tool call to execute (e.g. "ot.debug()"). Omit to use stdin.
Pass - to read the command from stdin
Pass a path to an existing .py file to read and execute its contents

Options:

Flag	Short	Default	Description
`--config PATH`	`-c`	—	Path to `onetool.yaml`; required for in-process execution
`--secrets PATH`	`-s`	—	Path to secrets file
`--format MODE`	`-f`	`json_h`	Output format: `json_h`, `json`, `yml`, `yml_h`, `raw`
`--no-host`		false	Skip server routing; always run in-process (requires --config)
`--sanitize`		false	Enable output sanitization (for AI pipeline use)
`--timeout N`	`-t`	from config	Server request timeout in seconds (overrides `direct.timeout`)

Output formats:

Mode	Description
`json_h`	Human-readable JSON with 2-space indent (default)
`json`	Compact JSON (no whitespace)
`yml`	YAML
`yml_h`	Human-readable YAML
`raw`	Raw result string with no serialisation

Format is injected into the execution namespace as __format__. Exit code communicates success (0) or failure (1). No envelope wrapper.

Server routing: without --no-host, direct run probes for a running execution server and routes to it if found. Falls back to in-process when none is detected. If direct.host: enable is set and no server is running, one is auto-started.

Exit codes:

0 — success
1 — tool execution error or server error
2 — config/argument error

Examples:

onetool direct run --config .onetool/onetool.yaml "ot.debug()"
echo "ot.version()" | onetool direct run --config .onetool/onetool.yaml -
onetool direct run --config .onetool/onetool.yaml report.py
onetool direct run --config .onetool/onetool.yaml "brave.search(query='AI')" --format json
onetool direct run "ot.version()"            # routes to server if running
onetool direct run --no-host --config .onetool/onetool.yaml "ot.version()"
onetool direct run "ot_llm.transform(data='...', prompt='summarise')" --timeout 120

onetool direct repl¶

Launch an interactive REPL for tool execution with persistent in-process state.

onetool direct repl [OPTIONS]

Options:

Flag	Short	Description
`--config PATH`	`-c`	Path to `onetool.yaml` (required)
`--secrets PATH`	`-s`	Path to secrets file

Features:

Prompt: >>> (continuation: ...)
Tab completion on pack.tool names, :quit, exit(), quit(), :help
Up/down arrow history, persisted to ~/.onetool/repl_history (1000 entries)
Multi-line input: unclosed brackets/blocks show ... prompt; empty line terminates a block
Spinner shown during execution
Pack state persists within a session (module-level state survives across lines)
Exit: :quit, exit(), quit(), or Ctrl+D
Ctrl+C cancels the current input/execution without exiting
:help prints available packs and tools

Requires an interactive terminal (TTY). Non-TTY stdin exits with code 1.

onetool direct list¶

List available tools, one per line (pipe-friendly).

onetool direct list [OPTIONS] [PATTERN]

Arguments:

PATTERN — pack name (e.g. brave) or glob pattern (e.g. brave.*); optional

Options:

Flag	Short	Default	Description
`--config PATH`	`-c`	—	Path to `onetool.yaml` (built-in packs shown without config)
`--info MODE`	`-i`	`min`	`min` (names only) or `full` (signature + description)

Examples:

onetool direct list                                      # all packs
onetool direct list brave                                # tools in brave pack
onetool direct list "brave.*"                           # glob pattern
onetool direct list --config onetool.yaml brave         # with explicit config
onetool direct list --info full | head -20              # signatures + docs
onetool direct list | fzf                               # interactive picking

onetool direct search¶

Find tools by name or description.

onetool direct search [OPTIONS] QUERY

Arguments:

QUERY — search phrase (e.g. "web search", "convert pdf")

Options:

Flag	Short	Description
`--config PATH`	`-c`	Path to `onetool.yaml`

Examples:

onetool direct search "web search"
onetool direct search "convert pdf"
onetool direct search --config onetool.yaml "database query"

onetool direct help¶

Show tool signatures, parameters, and docstrings.

onetool direct help [OPTIONS] [QUERY]

Arguments:

QUERY — tool name (brave.search), pack name (brave), or search phrase; optional

Options:

Flag	Short	Default	Description
`--config PATH`	`-c`	—	Path to `onetool.yaml`
`--info MODE`	`-i`	`full`	`min`, `default`, or `full`

Examples:

onetool direct help brave.search        # full signature + docstring for one tool
onetool direct help brave               # all tools in a pack with descriptions
onetool direct help "web search"        # fuzzy search across all tools
onetool direct help --config onetool.yaml brave.search

onetool direct servers¶

List configured proxy servers and their connection status.

onetool direct servers [OPTIONS] [PATTERN]

Arguments:

PATTERN — filter by server name; optional

Options:

Flag	Short	Default	Description
`--config PATH`	`-c`	—	Path to `onetool.yaml`
`--info MODE`	`-i`	`default`	`min`, `default`, or `full`

Examples:

onetool direct servers --config onetool.yaml
onetool direct servers github
onetool direct servers --info full

onetool direct start¶

Start the HTTP execution host.

onetool direct start [OPTIONS]

Options:

Flag	Short	Default	Description
`--config PATH`	`-c`	—	Path to `onetool.yaml`
`--secrets PATH`	`-s`	—	Path to secrets file
`--port N`	`-p`	`direct.port` or `8765`	Port to listen on

Starts the HTTP execution host as a daemon, then blocks until it is ready to accept connections (up to 5 seconds). PID and log are written to ~/.onetool/direct-server-{port}.pid and direct-server-{port}.log.

When --config is omitted, the host starts with no tools loaded (a warning is printed).

The host exposes POST /run accepting {"command": "..."} and returning {"result": "...", "success": true|false}.

onetool direct stop¶

Stop the running execution host.

onetool direct stop [--port N]

Reads ~/.onetool/direct-server-{port}.pid, sends SIGTERM (Unix) or TerminateProcess (Windows), then removes the PID file. Exits 0 if the host was stopped successfully or was not running; exits 1 if the process could not be terminated.

onetool direct status¶

Show execution server status.

onetool direct status [--port N]

Prints to stderr: Execution server running — PID <pid>, port <port>, uptime <N>s followed by Log: <path>.

Exit codes: 0 running, 1 not running.

onetool direct restart¶

Stop and restart the execution host in one command.

onetool direct restart [OPTIONS]

Reuses the saved --config and --port from the previous start. Explicit flags override the saved values. If no host is running, starts fresh.

Options: --config, --secrets, --port (same as start)

onetool direct logs¶

Print the last N lines of the server log.

onetool direct logs [--port N] [--lines N]

Flag	Short	Default	Description
`--port N`	`-p`	`8765`	Port of the server
`--lines N`	`-n`	`50`	Number of lines to show