명령 찾기와 실행

명령 형식#

stly <resource> <action> [id] [옵션]

예를 들어 stly apis get <id>는 API 하나를 조회합니다. 전체 명령은 stly --help와 stly cli list로 확인합니다.

명령 찾기#

하려는 일을 설명하면 stly cli search가 가까운 명령을 찾습니다. 서버에 연결하지 않습니다.

stly cli search "Endpoint 수정"

data의 각 항목은 command·summary·HTTP method·path·mutates(기록을 바꾸는지)를 담습니다. command 값을 그대로 다음 명령에 사용합니다.

stly cli search는 실행할 명령을 찾습니다. 저장된 Catalog 기록은 목록 명령의 --q나 stly catalog search로 찾습니다.

입력 스키마#

stly schema apis create

스키마는 명령의 인수·옵션, --if-match 필요 여부, 입력 JSON의 구조(request_schema)와 응답 필드를 알려 줍니다. 서버에 연결하지 않으며 example에 실행 예가 들어 있습니다.

입력 전달#

생성·수정 명령은 --input으로 JSON을 받습니다. 파일 경로 또는 -(stdin)를 씁니다.

stly apis create --input api.json
echo '{"name": "Payments API", "handle": "payments-api"}' | stly apis create --input -

dry-run#

--dry-run은 보낼 요청의 Method·Path·본문·인증 방식을 보여 주고 서버에는 요청하지 않습니다. 로그인 정보와 파일을 읽지 않으며, 서버 검증을 통과한다는 뜻은 아닙니다.

stly apis create --input api.json --server https://api.structly.io --dry-run

--server를 생략하면 결과의 origin은 null입니다. 요청 대상을 고정하려면 dry-run과 실제 실행에 같은 --server를 지정합니다.

일부 Catalog는 저장하지 않고 서버에서 입력을 검사하는 validate 명령을 제공합니다. stly cli search "검증"으로 지원 명령을 찾습니다.

출력 형식#

성공하면 stdout에 JSON 한 개를 출력하고 종료 코드 0으로 끝납니다.

{"status":200,"etag":null,"location":null,"data":[{"id":"4pkKFh2ojXs","name":"Orders API"}]}

--fields id,name처럼 지정하면 data의 최상위 필드만 남깁니다. 빈 목록은 data가 []인 정상 결과입니다.

오류와 종료 코드#

실패하면 stdout은 비어 있고 stderr에 오류 JSON 한 개를 출력합니다.

{"kind":"http","status":409,"error":{"code":"409.000","reason":"ORGANIZATION_REQUIRED","message":"현재 Organization이 선택되지 않았습니다.","data":[]},"outcome":"read_failed","hints":["stly org list --server 'https://api.structly.io' --auth-mode user","stly org select '<id>' --server 'https://api.structly.io' --auth-mode user"]}

outcome은 요청 결과를 알려 줍니다.

자주 만나는 오류는 FAQ를 참고합니다.

피드백 보내기#

stly feedback submit --type bug --title "요약 제목" --message "현상과 기대 동작" --source user

--type·--title·--message·--source가 필요하고, 실행한 명령은 --command, 오류 코드는 --error-code, 재현 순서는 --reproduction-steps로 더할 수 있습니다. 성공하면 data에 접수 ID가 있으며 --fields id로 ID만 받을 수 있습니다.

• 보내기 전에 토큰·비밀번호·Cookie·Authorization 같은 값을 [REDACTED]로 바꿉니다. 모든 비밀정보를 찾는다고 보장하지 않으므로 --dry-run으로 마스킹된 내용을 먼저 확인합니다.
• AI Agent가 --source ai-agent로 보내려면 사용자가 같은 명령에 --approved를 붙이거나 STLY_FEEDBACK_AGENT_OPT_IN=true를 설정해야 합니다. 그렇지 않으면 아무것도 보내지 않고 종료 코드 2로 끝납니다.
• 결과를 알 수 없는 오류(unknown)는 같은 명령을 그대로 다시 실행하면 같은 접수로 처리됩니다. 한도 초과(429)는 안내된 시간 뒤에 다시 실행합니다.
• 이 명령은 stly api로 직접 호출할 수 없습니다.

공통 옵션#