직장인 개발자를 위한 터미널 관심종목 뷰어 — ls + 주식, KOSPI/KOSDAQ. 근무 중에 몰래 종목을 확인하고, 상사가 지나가면 한 키로 htop·vim으로 위장하세요.

lstonks watch · 한국어	lstonks watch · English

관심종목을 한 번만 출력하거나, 실시간 전체화면 TUI로 띄웁니다. 시세는 네이버 금융 폴링 엔드포인트에서 가져오며(API 키 불필요), NXT 시간외 단일가 (애프터마켓/프리마켓)까지 포함하고 없으면 정규장 종가(종가)로 대체합니다.

lstonks          # 관심종목을 한 번 출력하고 종료
lstonks watch    # 실시간 전체화면 TUI (자동 갱신)

watch 모드 단축키:

기본값은 한국식 색상 관례 — 상승 = 빨강, 하락 = 파랑 — 이며, 설정에서 서양식(상승 = 초록)과 단색(mono)으로 바꿀 수 있습니다.

e 화면에서 종목에 별칭을 붙일 수 있습니다 — 코드에 1:1로 묶인 표시 이름 (예: 삼성전자를 samsung-driver로 표시). 별칭은 관심종목 목록에서만 이름을 덮어씁니다(TUI 행과 list 명령); 검색 결과에는 항상 실제 이름이 나오므로 종목은 그대로 찾을 수 있습니다. 별칭 칸을 비우면 실제 이름으로 돌아갑니다. 별칭은 portfolio.json에 종목별로 저장됩니다(alias).

종목을 폴더로 묶을 수 있고, 폴더는 원하는 만큼 깊게 중첩됩니다. 폴더는 ▾(열림) / ▸(닫힘) 표시를 보여주고, 내용이 없는 열린 폴더는 (empty) 줄을 표시합니다. 각 폴더 행은 그 안에 담긴 모든 보유 종목의 평가액·손익·수익률 합계도 — 접혀 있을 때조차 — 종목과 같은 열에 정렬해 보여줍니다.

이동(m) 중 폴더는 집어 든 행과 이렇게 상호작용합니다:

• 닫힌 폴더는 하나의 덩어리로 건너뜁니다.
• 열린 폴더로 다가가면 두 단계로 중첩됩니다: 폴더 쪽으로 처음 누르면 준비 상태가 되고(표시가 ⇱로 바뀌고 행은 제자리), 같은 방향으로 한 번 더 누르면 폴더의 가까운 가장자리로 행이 들어갑니다.
• 폴더 안에서는 j/k로 자식들 사이 순서를 바꾸고, 맨 위(또는 맨 아래) 가장자리를 넘어 밀면 행이 폴더 밖 위(또는 아래)로 튀어나옵니다.

종목 위에서 c를 누르면 분봉 캔들 차트가 열립니다 — 가격 축을 공유하는 전체 셀 캔들, 아래쪽 거래량 스트립, 실시간 현재가 선, 그리고 당일 등락률. 1 / 3 / 5로 봉 간격(1분 / 3분 / 5분)을 바꾸고, ← / →(또는 h / l)로 과거로 이동, g / G로 가장 오래된 쪽 / 실시간으로 점프, Esc / c / q로 닫습니다.

캔들은 설정된 손익 색상 관례를 그대로 따릅니다(설정 s, 또는 lstonks config color kr|us|mono):

한국식 · 상승 ▲ 빨강 / 하락 ▼ 파랑	서양식 · 상승 ▲ 초록 / 하락 ▼ 빨강	단색(Mono)

watch 화면은 위장을 걸칠 수 있습니다 — 한눈에 주식 티커가 아니라 다른 터미널 프로그램처럼 보이게요. 자리에서 종목을 보고 있다는 걸 티내고 싶지 않을 때를 위한 기능입니다. 설정 화면(s → 테마 / Theme)이나 CLI에서 바꿉니다:

lstonks config theme vim     # watch 화면 위장
lstonks config theme default # 원래 레이아웃으로

모든 위장은 기본 화면과 같은 실시간 숫자를 보여주고 같은 키에 반응하며, 설득력을 위해 빨강/파랑 손익 색상 대신 흉내 낸 도구 고유의 색을 씁니다. 위장 아래에서는 폴더가 평평하게 펼쳐집니다. 선택값은 settings.json에 저장됩니다 (theme). 새 위장을 추가하는 건 스킨 레지스트리(internal/ui/skins.go) 항목 하나와 렌더 함수 하나면 됩니다 — 모든 스킨이 같은 leafRows 스냅샷을 읽으므로 데이터나 갱신 코드는 건드릴 필요가 없습니다.

기본 출력과 watch 외에도, lstonks는 스크립트로 쓸 수 있는 하위 명령을 제공합니다. 모든 데이터 명령은 기계가 읽기 좋은 출력을 위한 --json을 받습니다(에이전트에 유용).

lstonks                                 # 관심종목 출력 (기본)
lstonks list --json                     # 관심종목을 JSON으로 (가격, 손익, …)
lstonks search 삼성 --json               # 티커 검색 (이름 또는 코드)
lstonks add 005930 --qty 5 --avg 70000  # 코드로 추가, 보유 포함
lstonks add "Samsung Electronics"       # 이름으로 추가 (검색 상위 매칭)
lstonks set 005930 --qty 10             # 수량 / 평균단가 수정
lstonks remove 005930                   # 티커 삭제 (별칭: rm)
lstonks quote 005930 000660 --json      # 임의 코드의 실시간 시세
lstonks value --json                    # 포트폴리오 평가액 + 손익
lstonks config lang en                  # 설정 변경 (lang ko|en, color kr|us|mono)
lstonks config theme vim                # watch 화면 위장 (default|vim|htop)
lstonks config                          # 현재 설정 보기
lstonks help                            # 전체 명령 목록

명령 표면은 작은 레지스트리입니다(cmd/lstonks/commands.go): 하위 명령 추가는 항목 하나와 run 함수 하나. 플래그와 위치 인자는 순서에 상관없이 올 수 있습니다. 변경 명령은 TUI가 쓰는 것과 같은 portfolio.json / settings.json에 기록하므로 CLI와 TUI가 항상 동기화됩니다.

• 시세: 네이버 금융 폴링 엔드포인트 (비공식; 준실시간).
• 장 구분 로직: 정규장 → NXT 애프터마켓/프리마켓 → 시간외 단일가 → 장 닫힘.
• 영어 이름: 영어 모드(설정 → Language)에서는 이름을 야후 파이낸스(비공식 검색 엔드포인트)에서 가져옵니다. 실시간 검색은 영어도 받고(예: "Samsung Electronics") 행에는 영문 회사명이 표시됩니다. 확인된 이름은 portfolio.json(nameEn)에 캐시되어 티커당 네트워크 조회는 한 번만 일어납니다. 시세는 항상 네이버에서.
• 관심종목 / 포트폴리오: ~/.config/lstonks/portfolio.json에 트리로 저장됩니다 (종목은 코드, 선택적 한/영 이름, 수량과 평균단가를; 폴더는 이름, 열림/닫힘 상태, 중첩 children를 가짐). LSTONKS_CONFIG_DIR로 설정 디렉터리 위치를 옮길 수 있습니다. 한 번 출력 모드는 폴더를 평평하게 펼쳐 종목만 출력합니다.

go build -o ~/.local/bin/lstonks ./cmd/lstonks

Go 1.24+ 필요. watch에서 한글을 입력하려면 UTF-8 터미널(과 한글 IME)이 필요합니다; 최신 터미널(GNOME Terminal, iTerm2, Windows Terminal)은 IME 조합을 커서 위치에 놓습니다.

편집→실행 루프를 빠르게 돌리려면, 바이너리 대신 래퍼를 PATH에 두어 lstonks를 실행할 때 소스가 오래됐으면 다시 빌드하게 하세요:

# 래퍼와 나란히 실제 바이너리를 빌드.
go build -o ~/.local/bin/lstonks.bin ./cmd/lstonks

그다음 ~/.local/bin/lstonks를 작은 스크립트로:

#!/usr/bin/env bash
set -euo pipefail
SRC="$HOME/Developer/lstonks"
BIN="$HOME/.local/bin/lstonks.bin"
GO="$(command -v go || echo /usr/local/go/bin/go)"

stale() {
  [ ! -x "$BIN" ] && return 0
  [ "$SRC/go.mod" -nt "$BIN" ] && return 0
  [ "$SRC/go.sum" -nt "$BIN" ] && return 0
  [ -n "$(find "$SRC/cmd" "$SRC/internal" -name '*.go' -newer "$BIN" -print -quit 2>/dev/null)" ] && return 0
  return 1
}

if stale; then
  echo "lstonks: source changed — rebuilding…" >&2
  ( cd "$SRC" && "$GO" build -o "$BIN" ./cmd/lstonks ) || \
    echo "lstonks: build failed — running previous binary" >&2
fi
exec "$BIN" "$@"

이제 소스 편집 → lstonks 실행은 항상 최신을 실행합니다. 재빌드는 .go/go.mod/ go.sum 파일이 바이너리보다 새로울 때만 일어나고(증분, ~0.5초), 알림은 stderr로 가므로 --json 출력은 파이프에 깨끗하게 유지됩니다. 빌드 실패 시 마지막으로 동작하던 바이너리로 대체됩니다. git pull도 파일 mtime을 갱신하므로 새 커밋을 받으면 다음 실행에서 다시 빌드됩니다.