yachiyo-help

name	yachiyo-help
description	Complete reference for the Yachiyo CLI — soul traits, provider management, agent profiles, config, thread search, scheduled tasks, channel users/groups, group monitor status control, and send commands

Yachiyo Help

Reference for the Yachiyo CLI. The binary lives at ~/.yachiyo/bin/yachiyo.

IMPORTANT: The Yachiyo CLI (yachiyo command) is NOT the Yachiyo desktop app (Yachiyo.app). You are running inside Yachiyo.app — never attempt to open, run, or execute Yachiyo.app via the bash tool. Doing so would spawn a recursive instance and is blocked by the security layer.

Read the detailed reference for each namespace before running unfamiliar commands:

• soul.md — Manage evolving persona traits
• providers.md — Manage AI providers
• agents.md — Manage coding agent profiles
• config.md — Read and write configuration values
• threads.md — Search historical conversations
• schedule.md — Manage scheduled tasks and view run history
• channel.md — List channel users/groups and change group monitor status
• send.md — Send notifications and channel messages

Usage

yachiyo <namespace> <subcommand> [args...] [flags...]

Namespaces

Namespace	Purpose	Reference
soul	Manage evolving persona traits	soul.md
provider	Manage AI providers	providers.md
agent	Manage coding agent profiles	agents.md
config	Read and write configuration	config.md
thread	Search historical conversations	threads.md
schedule	Manage scheduled tasks	schedule.md
channel	List channel users/groups and change group monitor status	channel.md
send	Send notifications and channel messages	send.md

Launch on Login (macOS)

This only applies when the user's system is darwin (macOS).

To make Yachiyo.app start automatically on user login, create and load a LaunchAgent plist:

1. Write the plist file

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>sh.ringo.yachiyo</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/open</string>
        <string>/Applications/Yachiyo.app</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

Save it to ~/Library/LaunchAgents/sh.ringo.yachiyo.plist.

2. Load the agent

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/sh.ringo.yachiyo.plist

3. Confirm it is active

launchctl list | grep sh.ringo.yachiyo

Global Flags

Flag	Description
--payload <json>	Supply a JSON body for mutation commands
--limit <n>	Max results for listing commands
--json	Output raw JSON for programmatic parsing

Key Paths

Path	Purpose
~/.yachiyo/config.toml	All settings: providers, tools, skills, memory, web search
~/.yachiyo/SOUL.md	Assistant persona and evolving trait log
~/.yachiyo/USER.md	User profile — who you are, your context, working style
~/.yachiyo/yachiyo.sqlite	Thread and message database
~/.yachiyo/bin/yachiyo	CLI wrapper (auto-generated, do not edit)

Troubleshooting: yachiyo: command not found

When a user reports that yachiyo is not found after first install, follow these steps in order:

1. Check if the wrapper exists

ls -la ~/.yachiyo/bin/yachiyo

If the file is missing, the user should re-launch the Yachiyo desktop app — it auto-generates the wrapper on startup.

2. Check for the /usr/local/bin symlink

ls -la /usr/local/bin/yachiyo

If the symlink exists and points to ~/.yachiyo/bin/yachiyo, the CLI should work immediately. If not, check whether /usr/local/bin exists and is writable:

ls -ld /usr/local/bin

If the directory is missing or not writable, you can create the symlink manually (may need sudo):

sudo mkdir -p /usr/local/bin
sudo ln -sf ~/.yachiyo/bin/yachiyo /usr/local/bin/yachiyo

3. Check PATH (fallback when symlink is unavailable)

If /usr/local/bin symlink is not an option, verify that ~/.yachiyo/bin is on the user's PATH:

echo $PATH | tr ':' '\n' | grep yachiyo

If missing, check the shell profile for the PATH entry:

• zsh: grep yachiyo ~/.zshrc
• bash: grep yachiyo ~/.bashrc ~/.bash_profile
• fish: grep yachiyo ~/.config/fish/config.fish

If the entry is missing, re-launch the Yachiyo desktop app to have it added automatically, or add it manually:

• zsh/bash: export PATH="$HOME/.yachiyo/bin:$PATH" in the appropriate profile
• fish: fish_add_path ~/.yachiyo/bin

After editing a profile, the user must either open a new terminal or source the file (e.g., source ~/.zshrc).

4. Quick fix for the current session

If the user just needs it working right now without restarting the terminal:

# Works in any shell for the current session
export PATH="$HOME/.yachiyo/bin:$PATH"

Or for fish:

fish_add_path ~/.yachiyo/bin