oly

When to use

Use oly start instead of a direct terminal invocation when ANY of these apply:

• The command may prompt for input later.
• The session must survive terminal closes, disconnects, or agent handoff.
• Logs, replay, or auditability matter.
• Another human or agent may need to resume or inspect the work.

Do not use oly for short, non-interactive commands — a normal terminal is simpler.

Principles

• Supervisor mindset. Start the job, monitor it, intervene only when needed.
• Small tails first. Use --tail 40; expand only when context is insufficient.
• Fewer polls, longer waits. Set --timeout to match the expected next checkpoint — reduces churn and token cost.
• Machine-readable listing. Use oly ls --json --status running for scripting or structured decisions.

Workflow

1) Start

oly start --title "task 1" --cwd /path/to/dir --detach the_cmd --arg1 --arg2

2) Monitor

oly logs <ID> --tail 40 --no-truncate --wait-for-prompt --timeout 10s

• --wait-for-prompt — blocks until the session likely needs input or timeout expires.
• --timeout — accepts 250ms, 10s, 5m, 1h (default 5m). Shorten for fast tasks; lengthen for slow ones.
• Start with --tail 40; increase only when recent context is insufficient.

3) Send input

oly send <ID> "hello world!" key:enter
oly send <ID> oly-clipboard
oly send <ID> "cat " oly-file:/path/to/file key:enter

• Arguments are sent left-to-right. Plain text is literal; special keys use key: prefix.
• Keys: key:enter, key:ctrl+c, key:alt+x, key:shift+tab, key:up, key:down.
• Raw hex: key:hex:.... Piped stdin is supported when no positional chunks are given.
• Clipboard content uses oly-clipboard. Local file upload uses oly-file:<path>. This is normally used for remote node sessions.

Input strategy:

4) Lifecycle

oly attach <ID>      # Detach: Ctrl-], then d
oly update <ID> --title "better name"
oly update <ID> --title ""
oly update <ID> --tag prod --tag release
oly update <ID> --tag ""
oly stop <ID>
oly ls                # oly ls --json for agents

• oly update changes session metadata without restarting the session.
• --title "" clears the title. If --title is omitted, the existing title is kept.
• --tag "" clears all tags. If --tag is omitted, existing tags are kept.
• Repeating --tag replaces the full tag list with the provided tags.

5) Notify

oly notify <ID> --title "Done" --description "Summary." --body "Details."

• <ID> is optional — include it to link the notification to a specific session.
• Toggle per-session notifications: oly notify enable <ID> / oly notify disable <ID>.

Help

oly --help            # or: oly <command> --help