본문으로 건너뛰기

CLI 사용 가이드

Synapse SDK는 설정부터 플러그인 개발 및 코드 편집까지, 개발 워크플로우를 관리하기 위한 강력한 대화형 CLI를 제공합니다.

사전 요구 사항

CLI 명령을 사용하기 전에, 설치 가이드를 완료하고 환경이 설정되어 있는지 확인하세요 (uv run synapse 또는 가상 환경 활성화).

시작하기​

사용 가능한 명령과 옵션 표시:

synapse --help

설치된 버전 확인:

synapse --version

사용 가능한 명령​

CLI는 다음과 같은 주요 명령 그룹을 제공합니다:

  • synapse login - Synapse 백엔드 인증
  • synapse plugin - 플러그인 개발 및 관리
  • synapse agent - 에이전트 설정
  • synapse mcp - AI 어시스턴트 통합을 위한 MCP 서버
  • synapse doctor - 설정 진단 실행

인증​

login 명령으로 Synapse 백엔드에 인증합니다:

# 대화형 로그인
synapse login

# 토큰을 직접 지정
synapse login --token YOUR_ACCESS_TOKEN

# 사용자 지정 호스트로 로그인
synapse login --host https://api.synapse.example.com --token YOUR_TOKEN

설정 파일​

Synapse는 다음 위치에 설정을 저장합니다:

  • 자격 증명: ~/.synapse/config.json - 백엔드 호스트와 액세스 토큰

플러그인 관리​

종합적인 플러그인 개발 및 관리 도구:

플러그인 라이프사이클​

synapse plugin CLI는 플러그인을 스캐폴딩부터 배포까지 일곱 단계로 안내합니다:

Create → Develop → Configure → Validate → Publish → Archive → Distribute

라이프사이클의 "Archive" 와 "Distribute" 단계 — 변형(variant) 및 매니페스트 기반 일괄 작업 포함 — 에 대해서는 GitHub 아카이빙 가이드를 참조하세요.

새 플러그인 생성​

# 대화형 위저드
synapse plugin create

# 옵션과 함께
synapse plugin create --name "My Plugin" --category neural_net

위저드는 다음을 생성합니다:

  • 플러그인 디렉토리 구조
  • 설정 파일 (config.yaml)
  • 예제 플러그인 코드
  • 요구사항 및 의존성

플러그인 실행​

다양한 실행 모드로 플러그인을 테스트할 수 있습니다:

# 로컬 실행 (디버깅에 가장 적합)
synapse plugin run test --mode local

# Ray Actor 실행
synapse plugin run test --mode task --gpus 1

# Ray Jobs API와 로그 스트리밍
synapse plugin run train --mode job --params '{"epochs": 10}'

# Synapse 백엔드를 통한 원격 실행
synapse plugin run deploy --mode remote

실행 모드​

모드설명
local인-프로세스 실행, 디버깅에 가장 적합
taskRay Actor 실행 (로그 스트리밍 없음)
jobRay Jobs API와 로그 스트리밍 (원격 실행 권장)
remoteSynapse 백엔드 API를 통한 실행 (인증 필요)

플러그인 배포​

Synapse 백엔드에 플러그인을 배포합니다:

# 업로드 없이 미리보기
synapse plugin publish --dry-run

# Debug 모드로 배포 (백엔드만, GitHub 없음)
synapse plugin publish --debug

# 확인 프롬프트 건너뛰기
synapse plugin publish --yes

# 매니페스트 기반 일괄 배포 (GitHub로부터)
synapse plugin publish -m plugin.yaml

알아두면 좋은 점: 정식 배포 (--debug 없이) 는 설정이 되어 있을 때 자동으로 GitHub에 아카이빙합니다. 설정과 자세한 내용은 GitHub 아카이빙 가이드를 참조하세요.

GitHub 연동​

플러그인 소스 코드의 GitHub 자동 아카이빙을 구성합니다:

# GitHub 토큰과 조직 설정
synapse plugin github-setup

# GitHub 설정 제거
synapse plugin github-clear

GitHub 아카이빙, 변형(variant) 브랜치, 매니페스트 기반 일괄 작업에 대한 전체 가이드는 GitHub 아카이빙 가이드를 참조하세요.

명령 레퍼런스​

메인 명령​

synapse --help          # 도움말 표시
synapse --version       # 버전 표시
synapse login           # Synapse 인증
synapse plugin          # 플러그인 관리 명령
synapse agent           # 에이전트 설정 명령
synapse mcp             # MCP 서버 명령
synapse doctor          # 설정 진단 실행

Login 명령​

synapse login [OPTIONS]

Options:
  --host TEXT     Synapse API host
  --token, -t TEXT  Access token (will prompt if not provided)
  --help          Show this message and exit

Plugin 명령​

# 템플릿으로부터 새 플러그인 생성
synapse plugin create [OPTIONS]
  --path, -p PATH       Output directory (default: current)
  --name, -n TEXT       Plugin name
  --code TEXT           Plugin code (slug)
  --category, -c TEXT   Plugin category
  --yes, -y             Skip confirmation

# 플러그인 액션 실행
synapse plugin run ACTION [OPTIONS]
  --plugin, -p TEXT     Plugin code (auto-detects from config.yaml)
  --path PATH           Plugin directory (default: current)
  --params TEXT         JSON parameters
  --mode, -m TEXT       Executor mode: local, task, job, or remote
  --ray-address TEXT    Ray cluster address (for task/job modes)
  --gpus INTEGER        Number of GPUs to request
  --cpus INTEGER        Number of CPUs to request
  --input, -i TEXT      JSON input for inference (for infer action)
  --infer-path TEXT     Inference endpoint path (for infer action)
  --host TEXT           Synapse API host (for remote mode)
  --token, -t TEXT      Access token (for remote mode)
  --debug/--no-debug    Debug mode (default: enabled)
  --debug-sdk           Bundle local SDK with upload (for SDK development)

# 플러그인 릴리스 배포
synapse plugin publish [OPTIONS]
  --path, -p PATH       Plugin directory (default: current)
  --config, -c PATH     Config file path
  --manifest, -m PATH   Manifest file for batch publish
  --host TEXT           Synapse API host
  --token, -t TEXT      Access token
  --dry-run             Preview without uploading
  --debug               Debug mode (bypasses backend validation)
  --yes, -y             Skip confirmation

# GitHub 연동 구성
synapse plugin github-setup [OPTIONS]
  --token, -t TEXT      GitHub personal access token (repo scope)
  --org, -o TEXT        GitHub organization name

# GitHub 설정 제거
synapse plugin github-clear [OPTIONS]
  --yes, -y             Skip confirmation

# 액션 자동 발견 및 설정 동기화
synapse plugin update-config [OPTIONS]
  --path, -p PATH       Plugin directory (default: current)
  --config, -c PATH     Config file path

# 잡(Job) 관리
synapse plugin job get JOB_ID [OPTIONS]
  --host TEXT           Synapse API host
  --token, -t TEXT      Access token

synapse plugin job logs JOB_ID [OPTIONS]
  --follow, -f          Follow log output (stream)
  --host TEXT           Synapse API host
  --token, -t TEXT      Access token

Agent 명령​

# 대화형으로 에이전트 선택
synapse agent select [OPTIONS]
  --host TEXT           Synapse API host
  --token, -t TEXT      Access token

# 현재 에이전트 설정 표시
synapse agent show

# 에이전트 설정 제거
synapse agent clear [OPTIONS]
  --yes, -y             Skip confirmation

MCP 명령​

# AI 어시스턴트 통합을 위한 MCP 서버 시작
synapse mcp serve [OPTIONS]
  --config, -c PATH     Path to config file (default: ~/.synapse/config.json)

# MCP 설정 파일 초기화
synapse mcp init [OPTIONS]
  --config, -c PATH     Path to config file (default: ~/.synapse/config.json)
  --force, -f           Overwrite existing config file

Doctor 명령​

# Synapse 설정에 대한 진단 실행
synapse doctor

Doctor 명령​

synapse doctor 명령은 Synapse SDK 설정에 대한 종합적인 진단을 실행합니다.

사용법​

synapse doctor

검사 항목​

doctor 명령은 다음을 검증합니다:

  1. 설정 파일 존재 여부: ~/.synapse/config.json 이 존재하는지 확인
  2. 유효한 JSON 형식: 설정 파일이 올바른 JSON 형식인지 검증
  3. CLI 인증: 인증 자격 증명이 있는지 확인
  4. MCP 설정: MCP 서버 설정 확인
  5. 에이전트 설정: 에이전트 설정 검증
  6. 토큰 유효성: 인증 토큰이 유효한지 테스트
  7. 파일 권한: 설정 파일이 적절한 권한(600)을 가졌는지 확인

출력 예시​

✓ Configuration file exists
✓ Valid JSON format
✓ CLI authentication configured
⚠ MCP configuration has warnings
✓ Agent configuration valid
✓ Token is valid
✓ File permissions are secure

종료 코드​

  • 0: 모든 검사 통과
  • 1: 오류 발견 (반드시 수정 필요)

팁 & 모범 사례​

설정 관리​

  1. 토큰 보안: API 토큰을 안전하게 보관하고 정기적으로 교체하세요.
  2. 에이전트 선택: 에이전트의 용도를 식별할 수 있도록 설명적인 이름을 사용하세요.
  3. 백엔드 URL: 백엔드 URL이 개발 환경에서 접근 가능한지 확인하세요.

플러그인 개발​

  1. 로컬 테스트: 배포 전에 항상 --mode local 로 플러그인을 로컬에서 테스트하세요.
  2. Debug 모드: 초기 배포에서 문제를 조기에 잡기 위해 debug 모드를 사용하세요.
  3. 버전 관리: git을 사용해 플러그인 변경 사항을 추적하고 버전을 관리하세요.
  4. 설정 동기화: 새 액션을 추가한 후에는 synapse plugin update-config 를 실행하세요.

문제 해결​

인증 문제​

문제: "Not authenticated"

  • 해결책: synapse login 을 실행하여 백엔드 연결을 설정하세요.

문제: "Invalid token (401)"

  • 해결책: 새 API 토큰을 생성하고 다시 synapse login 을 실행하세요.

문제: "Connection timeout"

  • 해결책: 네트워크 연결과 백엔드 URL 접근 가능 여부를 확인하세요.

플러그인 문제​

문제: 워크스페이스에서 플러그인이 감지되지 않음

  • 해결책: 디렉토리에 유효한 config.yaml 파일이 있는지 확인하세요.

문제: 플러그인 실행 실패

  • 해결책: 플러그인 의존성과 문법을 확인하고, 먼저 --mode local 로 로컬에서 테스트하세요.

문제: 원격 모드 사용 시 "No agent configured"

  • 해결책: synapse agent select 를 실행하여 에이전트를 구성하세요.

추가 문제 해결 도움말은 문제 해결 가이드를 참조하세요.