커맨드라인 (aop)

PulseAd의 커맨드라인은 aop(또는 aop-hermes) — 직원이 터미널에서 Amazon 광고 계정을 운영하는 Agentic Operations CLI입니다. 각 브랜드에 Pulse Library, AOP Memory API, Snowflake/Aurora, 그리고 번들된 Amazon Ads / AMC / 분석 도구에 연결된 워크스페이스를 제공합니다.

설치

aop는 GitHub에서 uv로 설치합니다. 전제: uv, Python 3.11(uv가 관리), 그리고 먼저 설정된 로컬 Pulse Library(docs/<BRAND_CODE> 폴더가 있는 Obsidian 볼트).

# 1. uv 설치 (없다면)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. GitHub main에서 aop CLI 설치
uv python install 3.11
uv tool install --python 3.11 "git+https://github.com/PulseAd/aop-hermes.git@main"
uv tool update-shell        # `aop`를 PATH에 추가, 이후 새 셸 열기

# 3. 확인
aop --version
aop --help

상태는 $AOP_HOME(기본 ~/.aop-hermes) 아래에 있습니다: launcher.json(Pulse Library 루트), shared.env(Memory API + Snowflake/Aurora), workspaces.json, 모델 홈, .secrets/. 브랜드 워크스페이스는 ~/aop-workspaces/<BRAND_CODE> 아래.

업그레이드: aop update(uv tool 설치를 main에서 자체 업데이트). 제거: uv tool uninstall aop-hermes — aop clean은 상태를 리셋하지만 바이너리는 유지.

연결

한 명령으로 전부 연결됩니다: aop setup. 세 섹션을 거친 뒤 공유 GENERAL 워크스페이스를 등록하고 doctor를 실행합니다.

aop setup — Pulse Library, Memory API, 모델을 연결하고 doctor 리포트까지

연결하는 것:

Pulse Library — 브랜드 docs 위치(docs/<BRAND_CODE>); launcher.json에 저장.
AOP Memory API — base URL + API 키(브랜드 메모리 백엔드); shared.env에 저장.
모델 / 제공자 / 인증 — 제공자 + 모델을 골라 인증(Hermes가 관리).

aop setup                      # 대화형: pulse-library + memory + model, 이후 doctor
aop setup --json               # 상태 확인만 — doctor 리포트 출력, 프롬프트 없음

# 한 조각씩 재설정
aop setup pulse-library
aop setup memory   --base-url https://memory.internal.pulsead.io --api-key <KEY>
aop setup model    # 모델 피커 열기

실행 & 워크스페이스

인자 없이 aop를 실행하면 대화형 런처, 또는 브랜드를 바로 실행합니다.

aop — GENERAL과 브랜드별 워크스페이스를 나열하는 대화형 런처

aop                            # 대화형 런처 — 워크스페이스 선택/생성
aop launch ACME                # ACME 브랜드 워크스페이스로 바로 실행
aop launch ACME -- <hermes args>   # 추가 인자를 Hermes로 전달
aop launch ACME --no-update        # 자체 업데이트 프리플라이트 건너뛰기

워크스페이스는 두 종류: general(공유 GENERAL)과 brand. 브랜드 스코프 코드는 정규화되고(대문자, 예: ACME), Pulse Library의 docs/<BRAND_CODE>에 매핑되며, **자체 격리된 HERMES_HOME**을 받아 로그/상태/설정이 브랜드별로 분리됩니다. 첫 실행 시 브랜드 specialist 프로필과 브랜드 메모리가 자동 설정됩니다.

명령어 레퍼런스

▸시작하기

$ aop

대화형 워크스페이스 런처 열기

$ aop --version aop --help

버전 / 전체 명령 표면

$ aop setup

--json--pulse-library-root

pulse-library + memory + model 설정, GENERAL 등록, doctor 실행

$ aop setup pulse-library | memory | model

해당 조각만 재설정

◆실행 & 워크스페이스

$ aop launch <SCOPE>

--kind--profile--home--auto-create--no-update

워크스페이스에서 Hermes 실행

$ aop workspace list ws ls

--all--json

워크스페이스 목록

$ aop workspace create <SCOPE>

--kind brand|general--display-name--profile…

워크스페이스 생성

$ aop workspace show | edit | archive | restore <SCOPE>

워크스페이스 조회 / 편집 / 보관 / 복원

⦿연결

$ aop memory status

--scope--json

AOP Memory API 확인

$ aop memory setup

--base-url--api-key

Memory API 설정 저장

$ aop model show

소스 홈과 글로벌 모델 표시

$ aop model set <model> aop model edit

--provider

모델 + 인증 설정 / 편집

❖프로필 & 스킬

$ aop profiles list | plan | install | verify | relink

번들 specialist 프로필 관리

$ aop profiles sync-skills aop sync-skills

번들 PulseAd 스킬을 프로필에 동기화

↻유지보수

$ aop update

--check

GitHub main에서 CLI 자체 업데이트 후 스킬 동기화

$ aop clean --dry-run aop clean --yes

$AOP_HOME + AOP 워크스페이스 리셋 표시 / 실행

무엇에 연결되는가

Pulse Library — <root>/docs/<BRAND_CODE>의 브랜드 docs, 각 워크스페이스에 WIKI_PATH로 마운트.
AOP Memory API — 브랜드 메모리 백엔드(bootstrap, 브랜드 컨텍스트, 태스크, 인박스), 에이전트에 aop-memory 도구로 노출.
Snowflake(SNOWFLAKE_* + RSA 키)와 Aurora/MySQL(AURORA_*) — 분석 도구용.
번들 aop-tools — Amazon Ads, AMC, 분석, 페이싱, RTB, 리포트 등(Node + in-process), AOP_TOOLS_ROOT로 노출.

기타 명령 표면 (개발 / ops)

aop가 유일한 설치형 CLI입니다. 다른 저장소는 개발자·ops용 저장소 로컬 러너와 작업 러너를 제공하며, 패키지 CLI가 아닙니다:

pulsead-agents — 에이전트 직접 실행, 예: python -m agents.campaign_health.pipeline <BRAND> 또는 python -m agents.weekly_report.pipeline <BRAND> --publish; ops 콘솔은 FastAPI 서버 (uvicorn web.backend.main:app).
snowflake-semantic-agent — python src/main.py <payload.json>로 로컬 디스패치(기본 dry-run), 그리고 scripts/*.py 스모크/재생성 도구.
ai-api — CLI 바이너리 없음; Makefile(make dev / test / lint)이 FastAPI 앱을 실행하고 ./deploy.sh가 빌드·배포.