fix: improve CLI UX across stdout/stderr channels, TTY errors, help text, and docs (#29)

- Move all progress/status messages (Fetching, Checking, Converting,
  auto-detect) from stdout to stderr for proper pipe composability
- Unify non-TTY error messages with branded format and how-to-fix guidance
  via new require_tty() helper in interactive.rs
- Add is_tty() guards to create and presets install before interactive prompts
- Move presets install TTY check before network fetch to avoid wasteful requests
- Add Examples section to --help via clap after_help
- Add long_about descriptions to all subcommands (update, apply, create,
  presets list, presets install)
- Warn when --editor/--target flags are used with subcommands that ignore them
- Update README.md and README.ko.md: add OpenCode/iTerm2 editors,
  OpenCode/Obsidian/iTerm2 targets, fix theme store path, update usage example
- Bump version to 0.10.1

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: minsoo-web

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "chromaport"
-version = "0.10.0"
+version = "0.10.1"
 edition = "2021"
 description = "Migrate VS Code / Cursor / OpenCode / iTerm2 themes to Superset, Warp, Ghostty, OpenCode, Obsidian, iTerm2, and more"
 license = "MIT"

README.ko.md

@@ -78,12 +78,11 @@ CI 환경과 비대화형 셸에서는 자동으로 비활성화됩니다.
 ```
 $ chromaport
 > Select editor: Cursor
-> Select themes to migrate: One Monokai, Ayu Dark
-> Select target app: Superset
+> Select theme: One Monokai    (TUI 라이브 미리보기)
+> Select target app: Ghostty
 
-Converting 2 theme(s)...
-  ✔ One Monokai → ~/.config/chromaport/themes/one-monokai.json
-  ✔ Ayu Dark → ~/.config/chromaport/themes/ayu-dark.json
+Converting theme...
+  ✔ One Monokai → ~/chromaport/themes/one-monokai.json
 ```
 
 ### 명령어
@@ -99,8 +98,8 @@ Commands:
 
 Options:
   -v, --version          버전 출력
-  -e, --editor <EDITOR>  소스 에디터 [가능한 값: vscode, cursor]
-  -t, --target <TARGET>  대상 앱 [가능한 값: superset, warp, ghostty]
+  -e, --editor <EDITOR>  소스 에디터 [가능한 값: vscode, cursor, opencode, iterm2]
+  -t, --target <TARGET>  대상 앱 [가능한 값: superset, warp, ghostty, opencode, obsidian, iterm2]
   -h, --help             도움말 출력
 ```
 
@@ -110,7 +109,7 @@ Options:
 # 대화형 모드 — 에디터, 테마, 대상을 단계별로 선택
 chromaport
 
-# 비대화형 — 에디터와 대상을 직접 지정
+# 에디터/대상 선택 건너뛰기 — 직접 지정
 chromaport --editor vscode --target ghostty
 ```
 
@@ -155,10 +154,12 @@ chromaport 저장소에서 엄선된 프리셋 테마를 탐색하고 설치할
 
 ## 지원 에디터
 
-| 에디터  | 경로                    |
-| ------- | ----------------------- |
-| VS Code | `~/.vscode/extensions/` |
-| Cursor  | `~/.cursor/extensions/` |
+| 에디터   | 경로                                                        |
+| -------- | ----------------------------------------------------------- |
+| VS Code  | `~/.vscode/extensions/`                                     |
+| Cursor   | `~/.cursor/extensions/`                                     |
+| OpenCode | `~/.config/opencode/themes/`                                |
+| iTerm2   | `~/Library/Preferences/com.googlecode.iterm2.plist`         |
 
 ## 지원 대상
 
@@ -167,6 +168,9 @@ chromaport 저장소에서 엄선된 프리셋 테마를 탐색하고 설치할
 | Superset | `~/.superset/chromaport-themes/`에 기록 — Superset UI에서 가져오기               |
 | Warp     | `~/.warp/themes/`에 심볼릭 링크 — 실행 중 자동 감지                              |
 | Ghostty  | `~/.config/ghostty/themes/`에 심볼릭 링크 — 설정 파일 또는 리로드로 적용         |
+| OpenCode | `~/.config/opencode/themes/`에 심볼릭 링크 — 재시작 시 자동 감지                 |
+| Obsidian | 볼트의 `.obsidian/themes/`에 복사 — 설정 → 외관에서 활성화                       |
+| iTerm2   | `~/.config/iterm2/themes/`에 심볼릭 링크 — Color Presets에서 가져오기            |
 
 ---
 
@@ -175,7 +179,7 @@ chromaport 저장소에서 엄선된 프리셋 테마를 탐색하고 설치할
 1. 에디터 확장 디렉토리에서 `package.json`의 테마 기여(contribution)를 스캔
 2. VS Code 테마 JSON 파싱 (JSONC 주석 제거 및 `include` 상속 처리)
 3. 중간 표현(IR)으로 변환
-4. 중앙 테마 저장소(`~/.config/chromaport/themes/`)에 저장
+4. 중앙 테마 저장소(`~/chromaport/themes/`)에 저장
 5. 선택한 대상 형식으로 심볼릭 링크 또는 기록
 
 ---

README.md

@@ -70,12 +70,11 @@ Run `chromaport` and follow the interactive prompts:
 ```
 $ chromaport
 > Select editor: Cursor
-> Select themes to migrate: One Monokai, Ayu Dark
-> Select target app: Superset
+> Select theme: One Monokai    (with live TUI preview)
+> Select target app: Ghostty
 
-Converting 2 theme(s)...
-  ✔ One Monokai → ~/.config/chromaport/themes/one-monokai.json
-  ✔ Ayu Dark → ~/.config/chromaport/themes/ayu-dark.json
+Converting theme...
+  ✔ One Monokai → ~/chromaport/themes/one-monokai.json
 ```
 
 ### Commands
@@ -91,8 +90,8 @@ Commands:
 
 Options:
   -v, --version          Print version
-  -e, --editor <EDITOR>  Source editor [possible values: vscode, cursor]
-  -t, --target <TARGET>  Target app [possible values: superset, warp, ghostty]
+  -e, --editor <EDITOR>  Source editor [possible values: vscode, cursor, opencode, iterm2]
+  -t, --target <TARGET>  Target app [possible values: superset, warp, ghostty, opencode, obsidian, iterm2]
   -h, --help             Print help
 ```
 
@@ -102,7 +101,7 @@ Options:
 # Interactive mode — select editor, themes, and target step by step
 chromaport
 
-# Non-interactive — specify editor and target directly
+# Skip editor/target selection — specify directly
 chromaport --editor vscode --target ghostty
 ```
 
@@ -145,10 +144,12 @@ Browse and install curated preset themes from the chromaport repository.
 
 ## Supported editors
 
-| Editor  | Path                    |
-| ------- | ----------------------- |
-| VS Code | `~/.vscode/extensions/` |
-| Cursor  | `~/.cursor/extensions/` |
+| Editor   | Path                                                        |
+| -------- | ----------------------------------------------------------- |
+| VS Code  | `~/.vscode/extensions/`                                     |
+| Cursor   | `~/.cursor/extensions/`                                     |
+| OpenCode | `~/.config/opencode/themes/`                                |
+| iTerm2   | `~/Library/Preferences/com.googlecode.iterm2.plist`         |
 
 ## Supported targets
 
@@ -157,13 +158,16 @@ Browse and install curated preset themes from the chromaport repository.
 | Superset | Writes to `~/.superset/chromaport-themes/` — import via Superset UI              |
 | Warp     | Symlinks to `~/.warp/themes/` — auto-detected while running                      |
 | Ghostty  | Symlinks to `~/.config/ghostty/themes/` — apply via config or reload             |
+| OpenCode | Symlinks to `~/.config/opencode/themes/` — auto-detected on restart              |
+| Obsidian | Copies to vault's `.obsidian/themes/` — activate in Settings → Appearance        |
+| iTerm2   | Symlinks to `~/.config/iterm2/themes/` — import via Color Presets                |
 
 ## How it works
 
 1. Scans editor extension directories for `package.json` theme contributions
 2. Parses VS Code theme JSON (with JSONC comment stripping and `include` inheritance)
 3. Converts to an intermediate representation (IR)
-4. Saves to a central theme store (`~/.config/chromaport/themes/`)
+4. Saves to a central theme store (`~/chromaport/themes/`)
 5. Symlinks or writes to the selected target format
 
 ## Development

src/apply.rs

@@ -6,9 +6,7 @@ use crate::target::{self, LinkResult, PostWriteAction};
 use anyhow::Result;
 
 pub fn run() -> Result<()> {
-    if !interactive::is_tty() {
-        anyhow::bail!("Not a TTY. chromaport apply requires an interactive terminal.");
-    }
+    interactive::require_tty("chromaport apply")?;
 
     // ── 1. Load saved IRs ───────────────────────────────────────────────
     let ir_files = store::list_ir_files()?;
@@ -71,7 +69,7 @@ pub fn run() -> Result<()> {
 
     // ── 5. Select targets (with applied markers) ─────────────────────
     let selected_targets = if all_targets.len() == 1 && !applied[0] {
-        println!(
+        eprintln!(
             "\nTarget: {} (only detected target)",
             all_targets[0].display_name()
         );
@@ -91,7 +89,7 @@ pub fn run() -> Result<()> {
         // Write
         let written_path = match t.write(&selected_ir) {
             Ok(path) => {
-                println!(
+                eprintln!(
                     "  {} {} → {}",
                     console::style("✔").green(),
                     selected_ir.name,

src/cli.rs

@@ -5,7 +5,15 @@ use clap::{Parser, Subcommand, ValueEnum};
     version,
     about = "Migrate VS Code / Cursor / OpenCode / iTerm2 themes to Superset, Warp, Ghostty, OpenCode, Obsidian, iTerm2, and more",
     long_about = None,
-    disable_version_flag = true
+    disable_version_flag = true,
+    after_help = "\
+Examples:
+  chromaport                              Interactive mode (select editor, theme, target)
+  chromaport -e vscode -t ghostty         Import VS Code theme to Ghostty
+  chromaport apply                        Apply a saved theme to new targets
+  chromaport create                       Create a custom theme with color picker
+  chromaport presets list                 Browse available preset themes
+  chromaport presets install              Install preset themes"
 )]
 pub struct Cli {
     /// Print version
@@ -27,14 +35,23 @@ pub struct Cli {
 #[derive(Subcommand)]
 pub enum Command {
     /// Check for updates and upgrade chromaport
+    #[command(
+        long_about = "Check for updates and upgrade chromaport.\n\nChecks GitHub releases for new versions and auto-detects your install method\n(Homebrew or Cargo) to run the appropriate upgrade command.\nUse -y to skip the confirmation prompt."
+    )]
     Update {
         /// Skip confirmation prompt
         #[arg(short = 'y', long)]
         yes: bool,
     },
     /// Apply a saved theme to additional targets
+    #[command(
+        long_about = "Apply a saved theme to additional targets.\n\nOpens a TUI preview to select from themes saved in ~/chromaport/themes/,\nthen lets you choose which target apps to apply the theme to."
+    )]
     Apply,
     /// Create a custom theme from scratch
+    #[command(
+        long_about = "Create a custom theme from scratch.\n\nOpens an interactive color picker (HSL sliders + hex input) to choose\nbackground, foreground, and accent colors. A full palette is automatically\nderived from your 3 base colors."
+    )]
     Create,
     /// Manage preset themes
     Presets {
@@ -46,8 +63,14 @@ pub enum Command {
 #[derive(Subcommand)]
 pub enum PresetsAction {
     /// List available preset themes
+    #[command(
+        long_about = "List available preset themes.\n\nFetches the preset catalog from GitHub and displays each theme's name,\nauthor, license, and install status."
+    )]
     List,
     /// Install preset themes
+    #[command(
+        long_about = "Install preset themes.\n\nFetches available presets from GitHub and opens a multi-select prompt\nto choose which themes to download and save locally."
+    )]
     Install,
 }
 

src/create.rs

@@ -27,6 +27,7 @@ enum Phase {
 }
 
 pub fn run_create() -> Result<()> {
+    crate::interactive::require_tty("chromaport create")?;
     // 1. Dark/Light selection
     let options = vec!["Dark", "Light"];
     let theme_type = match inquire::Select::new("Theme type:", options).prompt() {

src/interactive.rs

@@ -8,6 +8,18 @@ pub fn is_tty() -> bool {
     std::io::stdin().is_terminal()
 }
 
+/// Guard: bail if not running in an interactive terminal.
+/// `context` is inserted into the message, e.g. "chromaport create" or "chromaport".
+pub fn require_tty(context: &str) -> Result<()> {
+    if is_tty() {
+        return Ok(());
+    }
+    anyhow::bail!(
+        "Not a TTY. {context} requires an interactive terminal.\n\
+         Run this command directly in your terminal."
+    );
+}
+
 /// Let user pick dark or light theme type.
 pub fn select_theme_type() -> Result<crate::ir::ThemeType> {
     let options = vec!["Dark", "Light"];
@@ -51,7 +63,7 @@ pub fn select_target(available: &[Target]) -> Result<Target> {
 
     if available.len() == 1 {
         let t = available[0].clone();
-        println!("Target: {} (auto-detected)", t.display_name());
+        eprintln!("Target: {} (auto-detected)", t.display_name());
         return Ok(t);
     }
 
@@ -186,7 +198,10 @@ pub fn select_vault(vaults: &[std::path::PathBuf]) -> Result<std::path::PathBuf>
 fn handle_inquire_error(e: InquireError) -> anyhow::Error {
     match e {
         InquireError::NotTTY => {
-            anyhow::anyhow!("Not a TTY. chromaport requires an interactive terminal.")
+            anyhow::anyhow!(
+                "Not a TTY. chromaport requires an interactive terminal.\n\
+                 Run this command directly in your terminal."
+            )
         }
         InquireError::OperationCanceled => {
             std::process::exit(0);

src/main.rs

@@ -34,6 +34,18 @@ fn run() -> Result<()> {
 
     // Handle subcommands
     if let Some(ref cmd) = cli.command {
+        if cli.editor.is_some() || cli.target.is_some() {
+            let cmd_name = match cmd {
+                Command::Update { .. } => "update",
+                Command::Apply => "apply",
+                Command::Create => "create",
+                Command::Presets { .. } => "presets",
+            };
+            eprintln!(
+                "Note: --editor/--target options are not used with the '{}' command.",
+                cmd_name
+            );
+        }
         match cmd {
             Command::Update { yes } => return update::run_update(*yes),
             Command::Apply => return apply::run(),
@@ -84,7 +96,7 @@ fn run() -> Result<()> {
                 )
             })?
     } else if all_editors.len() == 1 {
-        println!(
+        eprintln!(
             "Editor: {} (auto-detected)",
             match &all_editors[0].0 {
                 Editor::Vscode => "VS Code",
@@ -141,9 +153,7 @@ fn run() -> Result<()> {
     };
 
     // ── 4. Select theme (single-select with live preview) ─────────────────
-    if !interactive::is_tty() {
-        anyhow::bail!("Not a TTY. chromaport requires an interactive terminal.");
-    }
+    interactive::require_tty("chromaport")?;
 
     let selected_entry = match preview::select_theme_with_preview(
         &all_themes,
@@ -156,7 +166,7 @@ fn run() -> Result<()> {
     };
 
     // ── 5. Convert ────────────────────────────────────────────────────────
-    println!("\nConverting theme...");
+    eprintln!("\nConverting theme...");
     let theme_json = reader.read_theme_json(&selected_entry)?;
     let ir = converter::convert(&selected_entry, &theme_json)?;
 
@@ -204,9 +214,7 @@ fn run_opencode_import(cli: &Cli) -> Result<()> {
     };
 
     // Select theme
-    if !interactive::is_tty() {
-        anyhow::bail!("Not a TTY. chromaport requires an interactive terminal.");
-    }
+    interactive::require_tty("chromaport")?;
 
     let theme_names: Vec<String> = opencode_themes.iter().map(|(n, _)| n.clone()).collect();
     let selected_name = inquire::Select::new("Select OpenCode theme:", theme_names)
@@ -219,7 +227,7 @@ fn run_opencode_import(cli: &Cli) -> Result<()> {
         .unwrap();
 
     // Convert
-    println!("\nConverting theme...");
+    eprintln!("\nConverting theme...");
     let theme_type = converter_opencode::infer_theme_type(&theme_map);
     let ir = converter_opencode::convert_opencode(&name, &theme_map, theme_type)?;
 
@@ -263,9 +271,7 @@ fn run_iterm2_import(cli: &Cli) -> Result<()> {
     };
 
     // Select preset
-    if !interactive::is_tty() {
-        anyhow::bail!("Not a TTY. chromaport requires an interactive terminal.");
-    }
+    interactive::require_tty("chromaport")?;
 
     let preset_names: Vec<String> = presets.iter().map(|(n, _)| n.clone()).collect();
     let selected_name = inquire::Select::new("Select iTerm2 color preset:", preset_names)
@@ -281,7 +287,7 @@ fn run_iterm2_import(cli: &Cli) -> Result<()> {
     let theme_type = interactive::select_theme_type()?;
 
     // Convert
-    println!("\nConverting theme...");
+    eprintln!("\nConverting theme...");
     let ir = converter_iterm2::convert_iterm2(&name, &preset, theme_type)?;
 
     // Write, link, post-write, save IR
@@ -301,10 +307,10 @@ fn write_link_and_save(target: &Target, ir: &ir::ThemeIR) -> Result<()> {
     }
 
     // Write
-    println!();
+    eprintln!();
     let written_path = match target.write(ir) {
         Ok(path) => {
-            println!(
+            eprintln!(
                 "  {} {} \u{2192} {}",
                 console::style("\u{2714}").green(),
                 ir.name,