PyAEDT CLI 스킬

pyaedt CLI를 사용하여 ANSYS Electronics Desktop(AEDT)와 상호작용할 수 있습니다. 이 스킬은 효과적으로 사용하는 방법을 설명합니다.

사전 점검 (먼저 실행)

CLI 명령어를 실행하기 전에 pyaedt가 설치되어 있는지 확인하세요:

pyaedt --json version

명령어가 실패하면 중단하고, 사용자에게 all 설치 대상으로 설치하여 모든 기능을 활성화하도록 안내하세요.

pip install pyaedt[all]

CLI 호출

명령어를 실행하기 전에 pyaedt 바이너리를 한 번 확인하세요:

pyaedt를 직접 시도합니다. 시스템 PATH에 있으면 그대로 사용합니다.
찾을 수 없으면 현재 작업 디렉토리의 venv 로컬 바이너리로 대체합니다:
- Windows: .venv\Scripts\pyaedt
- Linux/macOS: .venv/bin/pyaedt

모든 예제는 간결성을 위해 pyaedt를 사용합니다. 필요한 경우 해결된 경로로 대체하세요.

생성된 아티팩트의 작업 디렉토리

사용자가 별도로 지정하지 않는 한 모든 내보내기 및 생성 파일에는 임시 디렉토리를 사용하세요.

규칙:

OS 임시 디렉토리 아래에 작업별 하위 디렉토리를 생성합니다.
Python에서는 tempfile.mkdtemp(prefix="pyaedt-skill-"), Windows에서는 $env:TEMP, Linux/macOS에서는 ${TMPDIR:-/tmp}를 사용합니다.
명시적으로 요청되지 않는 한 저장소나 임의의 폴더에 쓰지 마세요.
사용자가 유지하려는 경우에만 성공적인 내보내기 후 아티팩트를 임시 디렉토리에서 이동합니다.

빠른 참조:

import tempfile

temp_dir = tempfile.mkdtemp(prefix="pyaedt-skill-")

내보내기 명령어에서 --path 또는 --output에 이 경로를 전달하세요.

비대화형 명령어에는 --json 사용

모든 비대화형 명령어에는 --json을 사용하여 출력을 구조화되고 기계가 파싱 가능하게 유지하세요.

JSON 출력은 {"status": "ok", "data": {...}} 또는 {"status": "error", "error": "message"}를 반환합니다.

data를 사용하기 전에 항상 status 필드를 먼저 파싱하세요. 사람이 읽을 수 있는 출력에 의존하지 마세요.

예외:

session attach는 대화형 콘솔을 시작하므로 사람 모드가 허용됩니다.
doc 명령어는 브라우저 페이지를 열며 일반적으로 구조화된 자동화 출력으로 사용되지 않습니다.

현재 CLI 구조

명령어는 다음과 같이 구성됩니다:

pyaedt [--json] <group> <command> [options]

현재 CLI에서 사용 가능한 그룹:

session
project
script
export
test-config
panels
doc

최상위 명령어:

version
aedt-versions

현재 CLI에 존재하지 않는 다른 명령어 그룹이나 명령어를 임의로 만들지 마세요. 필요한 작업이 CLI에서 지원되지 않으면, 우회하지 말고 사용자에게 보고하세요.

포트 기반 모델

현재 CLI는 기본적으로 포트 기반입니다.

session start는 새 AEDT 인스턴스를 시작하고 gRPC 포트를 반환합니다.
session list는 실행 중인 AEDT 인스턴스를 검색합니다.
대부분의 운영 명령어에는 --port가 명시적으로 필요합니다.
session attach는 --project 또는 --design으로 기존 AEDT 세션을 선택하는 데 사용할 수도 있으므로 모든 워크플로우가 알려진 포트에서 시작되는 것은 아닙니다.
다시 사용할 수 있는 지속적인 session connect 상태는 없습니다.

실제 의미:

# AEDT 검색 또는 시작
pyaedt --json session list
pyaedt --json session start --version 2026.1 --non-graphical

# 그런 다음 원하는 명령어에 --port 전달
pyaedt --json project list --port 50051
pyaedt --json run my_script.py --port 50051

프로젝트 및 디자인 해상도 규칙

디자인 범위 명령어는 하나의 공유 해상도 규칙 집합을 사용합니다. 이는 중요하며 지침과 예제에서 일관되게 적용해야 합니다.

영향을 받는 명령어:

export screenshot
export config
session attach (--project 또는 --design과 함께 사용될 때)

해상도 규칙:

--project와 --design이 모두 제공되면 직접 사용합니다.
--project만 제공되면 해당 프로젝트에 정확히 하나의 디자인이 포함되어야 합니다.
--design만 제공되면 정확히 하나의 프로젝트가 열려 있어야 합니다.
둘 다 제공되지 않으면 정확히 하나의 열린 프로젝트와 그 안에 정확히 하나의 디자인이 있어야 합니다.
선택이 모호하면 명령어가 실패하고 누락된 선택자를 제공해야 합니다.

사용자를 도울 때, 명령어가 실제로 그 동작을 사용하지 않는 한 이 동작을 "활성 프로젝트" 또는 "활성 디자인" 대체로 설명하지 마세요. 의도된 동작은 고유성 기반 해상도입니다.

명령어 참조

최상위 명령어

명령어	설명
`pyaedt --json version`	PyAEDT 버전 표시
`pyaedt --json aedt-versions`	설치된 AEDT 버전 목록 표시

세션 관리

명령어	설명
`pyaedt --json session start --version 2026.1 [--port 50051] [--non-graphical]`	새 AEDT 인스턴스 시작
`pyaedt --json session list`	PID, 버전, 포트와 함께 실행 중인 AEDT 인스턴스 목록
`pyaedt --json session stop --port 50051`	특정 AEDT 인스턴스 중지 (포트 기준)
`pyaedt --json session stop --all`	모든 AEDT 인스턴스 종료
`pyaedt session attach [--port 50051] [--project NAME] [--design NAME]`	실행 중인 인스턴스에 연결된 대화형 PyAEDT 콘솔 실행

참고:

session attach는 --port를 생략하고 사용자가 인스턴스를 선택하면 대화형으로 작동할 수 있습니다.
--project 또는 --design과 함께 session attach를 사용하려면 사용 가능한 포트가 있는 gRPC 인스턴스에서만 작동합니다.

프로젝트 명령어

모든 프로젝트 명령어에는 대상 AEDT 인스턴스를 지정하기 위해 포트가 필요합니다.

명령어	설명
`pyaedt --json project list --port 50051`	열려 있는 모든 프로젝트와 해당 디자인 나열
`pyaedt --json project open "C:/path/to/file.aedt" --port 50051 [--non-graphical]`	AEDT 프로젝트 파일 열기
`pyaedt --json project save --port 50051 [--path "C:/new/file.aedt"]`	활성 프로젝트 저장 (선택적으로 새 파일로)
`pyaedt --json project create --name ProjectA --port 50051`	프로젝트 생성. `--name` 사용.
`pyaedt --json project create --project ProjectA --design Design1 --type Hfss --port 50051`	기존 프로젝트 내에 디자인 생성. `--project` + `--design` + `--type` 사용.
`pyaedt --json project close --port 50051 [--project ProjectA]`	프로젝트 닫기 (생략 시 활성 프로젝트)

project create 동작:

--name은 프로젝트 생성용입니다.
--project + --design + --type은 디자인 생성용입니다.
--name을 --design / --type과 혼합하지 마세요.

지원되는 --type 값:

Hfss
Maxwell2d
Maxwell3d
Q3d
Q2d
Icepak
Circuit
TwinBuilder
Mechanical
Emit
Rmxprt
Hfss3dLayout
MaxwellCircuit

스크립트 명령어

명령어	설명
`pyaedt --json run "path/to/script.py" --port 50051`	AEDT 내에서 Python 스크립트 실행

내보내기 명령어

명령어	설명
`pyaedt --json export screenshot --port 50051 [--path preview.jpg] [--project NAME] [--design NAME]`	해결된 디자인의 스크린샷 캡처
`pyaedt --json export config --port 50051 [--output config.json] [--project NAME] [--design NAME] [--overwrite]`	디자인 설정 JSON 내보내기

두 명령어 모두 디자인 범위이므로 위의 공유 프로젝트/디자인 해상도 규칙을 따릅니다.

문서

명령어	설명
`pyaedt doc`	문서 홈 페이지 열기 및 도움말 출력
`pyaedt doc examples`	예제 섹션 열기
`pyaedt doc github`	GitHub 저장소 열기
`pyaedt doc user-guide`	사용자 가이드 열기
`pyaedt doc getting-started`	시작 가이드 열기
`pyaedt doc installation`	설치 문서 열기
`pyaedt doc api`	API 참조 열기
`pyaedt doc changelog [VERSION]`	변경 로그 열기
`pyaedt doc issues`	이슈 페이지 열기
`pyaedt doc search <keywords>`	온라인 문서 검색

일반적인 워크플로우

워크플로우 1: AEDT 검색 또는 시작

# 실행 중인 인스턴스 확인
pyaedt --json session list

# 실행 중인 인스턴스가 없으면 하나 시작
pyaedt --json session start --version 2026.1 --non-graphical

결정 규칙:

session list가 프로세스를 반환하지 않으면 AEDT를 시작합니다.
하나의 프로세스를 반환하면 해당 포트를 재사용합니다.
여러 프로세스를 반환하면 사용자에게 사용할 포트를 묻습니다.

워크플로우 2: 포트의 프로젝트 검사

pyaedt --json project list --port 50051

필요한 프로젝트 및 디자인 선택자를 이해해야 할 때 먼저 사용하세요.

워크플로우 3: 프로젝트 또는 디자인 생성

# 프로젝트 생성. --name만 사용 (--design 또는 --type 추가 금지)
pyaedt --json project create --name "PatchAntenna" --port 50051

# 기존 프로젝트에 디자인 생성. --project + --design + --type만 사용 (--name 추가 금지)
pyaedt --json project create --project "PatchAntenna" --design "HFSSDesign1" --type Hfss --port 50051

워크플로우 4: session attach로 대화형 탐색

사용자가 디자인을 대화형으로 탐색, 디버그 또는 반복하고자 할 때 session attach를 첫 번째 선택으로 사용하세요. 이 명령어는 대상 AEDT 세션에 이미 연결된 대화형 Python 콘솔을 엽니다. desktop이 미리 주입되므로 전체 스크립트를 작성하지 않고도 PyAEDT 명령어를 하나씩 실행할 수 있습니다.

# 실행 중인 인스턴스에 연결 (포트는 선택 사항, 생략 시 프롬프트)
pyaedt session attach --port 50051

# 대화형 Python 콘솔 내부에서 세션이 이미 활성화되어 있습니다:
# >>> import ansys.aedt.core as aedt
# >>> hfss = aedt.Hfss(new_desktop=False, port=50051)
# >>> box = hfss.modeler.create_box([0, 0, 0], [10, 10, 10], name="MyBox")
# >>> hfss.modeler["MyBox"].color = (255, 0, 0)

대화형 Python 콘솔에 여러 줄 코드 보내기

에이전트가 한 줄 이상에 걸친 코드(루프, 조건문, 함수 정의 등)를 대화형 Python 콘솔에 보낼 때, 직접 붙여넣으면 콘솔이 각 줄을 별도의 입력으로 처리하기 때문에 IndentationError 또는 SyntaxError가 발생합니다.

항상 여러 줄 블록을 exec()로 감싸고, 단일 문자열 내에서 모든 개행을 \n으로 인코딩하세요:

# 실패: 콘솔이 루프 본문에서 분할되기 때문
for i in range(3):
    print(i)

# 올바름: 단일 exec() 호출로 전송
exec("for i in range(3):\n    print(i)")

규칙:

들여쓰기된 코드(루프, if, with, 함수 또는 클래스 정의)가 포함된 모든 블록에는 exec()를 사용하세요.
단일 문장 줄(import, 할당, 함수 호출)은 exec()가 필요하지 않습니다.
외부 구분자가 "인 경우 모든 내부 큰따옴표를 \"로 이스케이프하거나 위와 같이 연결된 문자열 리터럴을 사용하세요.
exec() 호출을 가능한 한 짧게 유지하세요. 블록이 약 10줄을 초과하면 임시 스크립트를 저장하고 run을 사용하는 것이 좋습니다.

session attach 명령어와 run 명령어 중 선택 기준:

상황	권장 접근 방식
디자인 상태 탐색, 목표 불명	`session attach`
실패하는 단계 대화형 디버그	`session attach`
일회성 형상/매개변수 조정	`session attach`
몇 가지 명령어로 빠르게 반복	`session attach`
정의된 반복 가능한 다단계 워크플로우	`run`
CI / 헤드리스 / 자동화 파이프라인	`run`
워크플로우가 약 5단계 이상인 경우	`run`
추적성 및 로깅 필요	`run`

먼저 session attach를 선호하세요. 워크플로우가 알려지고 반복 가능하거나 자동화가 필요할 때만 run으로 전환하세요.

여러 디자인 동시 작업

사용자가 한 번에 두 개 이상의 디자인을 작업해야 하는 경우, 단일 콘솔 내에서 디자인을 전환하는 대신 각 디자인에 대해 별도의 대화형 Python 콘솔을 여세요. 이렇게 하면 각 디자인을 닫거나 해제하지 않고도 라이브 상태로 유지되고 편집 가능합니다.

# 터미널 1: 디자인 A용 콘솔
pyaedt session attach --port 50051 --project "ProjectA" --design "DesignA"

# 터미널 2: 디자인 B용 콘솔 (같은 프로젝트 또는 다른 프로젝트)
pyaedt session attach --port 50051 --project "ProjectA" --design "DesignB"

# 터미널 3: 다른 프로젝트의 디자인용 콘솔
pyaedt session attach --port 50051 --project "ProjectB" --design "DesignC"

규칙:

각 콘솔은 특정 디자인에 바인딩된 자체 PyAEDT 객체를 보유합니다. 하나의 콘솔을 닫아도 다른 콘솔은 닫히지 않습니다.
모든 콘솔은 동일한 AEDT 인스턴스(동일한 --port)를 공유하므로 한 콘솔에서 변경한 내용이 AEDT에 즉시 표시됩니다.
이러한 콘솔 내에서는 의도적으로 모든 열린 콘솔에 대해 AEDT를 종료하려는 경우가 아니라면 desktop.release_desktop() 또는 aedt_app.release_desktop()를 호출하지 마세요.
디자인이 다른 AEDT 인스턴스에 있는 경우 각 콘솔에 일치하는 --port를 사용하세요.

워크플로우 5: 자동화 실행

pyaedt --json run "<temp-dir>/setup_antenna.py" --port 50051

워크플로우 6: 생성된 스크립트 실행

스크립트가 생성되어 자동으로 실행되어야 할 때마다 이 워크플로우를 사용하세요.

# 1단계: 인스턴스 검색
pyaedt --json session list

# 2단계: 필요한 경우 하나 시작
pyaedt --json session start --version 2026.1 --non-graphical

# 3단계: 선택한 포트에서 스크립트 실행
pyaedt --json run "<temp-dir>/generated_script.py" --port 50051

규칙:

항상 먼저 대상 포트를 결정하세요.
여러 인스턴스가 실행 중이면 전체 목록을 표시하고 사용할 포트를 물으세요.
워크플로우에 자동 실행이 필요한 경우 생성된 스크립트를 수동으로 실행하라고 사용자에게 말하지 마세요.
기존 AEDT 인스턴스용으로 의도된 생성된 스크립트는 new_desktop=False를 사용해야 합니다.

워크플로우 7: 디자인 데이터 내보내기

# 인스턴스에 프로젝트와 디자인이 정확히 하나씩 있으면 선택자 생략 가능
pyaedt --json export screenshot --port 50051 --path "<temp-dir>/preview.jpg"
pyaedt --json export config --port 50051 --output "<temp-dir>/config.json" --overwrite

# 모호한 경우 누락된 선택자 지정
pyaedt --json export screenshot --port 50051 --project "PatchAntenna" --design "HFSSDesign1" --path "<temp-dir>/preview.jpg"

워크플로우 8: 여러 인스턴스 관리

여러 AEDT 인스턴스가 실행 중일 때:

다른 인스턴스의 프로젝트와 디자인을 혼동하지 않도록 각 인스턴스의 포트를 추적하세요. 각 인스턴스는 독립적인 세션이므로 포트를 올바르게 지정하는 것이 필수적입니다.

# 인스턴스 1 (포트 50051): HFSS 설계
pyaedt --json project list --port 50051

# 인스턴스 2 (포트 50052): Maxwell 설계
pyaedt --json project list --port 50052

규칙:

각 AEDT 인스턴스는 고유한 포트 번호를 가집니다.
한 인스턴스의 포트에서 다른 인스턴스의 프로젝트나 디자인에 접근할 수 없습니다.
AEDT를 시작할 때 포트를 지정하지 않으면 시스템에서 사용 가능한 포트를 자동으로 할당합니다. session start의 JSON 출력에서 반환된 포트를 기록해 두세요.

오류 처리

일반적인 오류 및 해결 방법

오류	가능한 원인	해결 방법
`Connection refused`	AEDT 인스턴스가 실행 중이지 않음	`session start`로 시작
`Project not found`	프로젝트 경로 또는 이름이 잘못됨	`project list`로 올바른 이름 확인
`Design not found`	디자인 이름이 잘못됨	`project list`로 올바른 디자인 이름 확인
`Multiple designs found`	선택이 모호함	`--project` 및 `--design` 제공
`pyaedt: command not found`	PyAEDT가 설치되지 않음	`pip install pyaedt[all]`로 설치
`Version mismatch`	AEDT 버전이 PyAEDT와 호환되지 않음	호환되는 버전 확인 및 설치

오류가 발생했을 때 해야 할 일

JSON 출력의 status 필드를 확인하세요.
error 메시지를 자세히 읽으세요.
일반적인 원인을 진단하세요.
수정 사항을 적용하고 명령어를 다시 실행하세요.
문제가 지속되면 session list를 실행하여 AEDT 상태를 확인하세요.
필요하면 사용자에게 알리고 추가 지침을 요청하세요.

팁 및 모범 사례

성능 최적화

가능하면 그래픽 사용자 인터페이스 없이 --non-graphical 모드를 사용하세요.
AEDT 인스턴스를 재사용하여 시작/중지 오버헤드를 방지하세요.
대용량 프로젝트에서는 특정 디자인만 내보내 전체 데이터를 내보내지 마세요.

보안 고려 사항

스크립트를 실행하기 전에 항상 검증하세요.
프로젝트 경로가 예상 범위 내에 있는지 확인하여 무단 파일 접근을 방지하세요.
여러 사용자와 인스턴스를 공유하는 경우 각 세션에 고유한 포트를 사용하세요.

디버깅 팁

반환된 데이터를 검사하려면 명령어에 --json을 사용하세요.
디자인 상태를 대화형으로 탐색하려면 session attach를 사용하세요.
문제를 격리하려면 run 대신 짧은 스크립트를 사용하여 한 번에 한 단계씩 테스트하세요.
스크립트를 실행하기 전에 project list로 프로젝트 및 디자인 이름을 확인하세요.

즐겨 사용하는 AI에게 물어보기

문서