> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 터미널에 apiyi 명령을 찾을 수 없다고 표시되는 이유는 무엇인가요?

> npx apiyi@latest를 실행하면 CLI를 설치하지 않고 실행하므로 이후에 apiyi 명령을 사용할 수 없습니다. npx apiyi@latest 접두사를 유지하거나, npm i -g apiyi로 한 번 설치하세요.

## 짧은 답변

`npx apiyi@latest` **CLI를 다운로드해 한 번 실행하고 흔적을 남기지 않으므로**, `apiyi` 명령이 시스템에 추가되지 않습니다. 이후 명령을 실행할 때마다 `npx apiyi@latest …` 전체 접두사를 입력해야 합니다. 예를 들어 키를 저장하려면 다음과 같이 입력합니다.

```bash theme={null}
npx apiyi@latest auth set-key
```

앞으로 `apiyi`만 입력하려면 한 번 전역으로 설치합니다: `npm i -g apiyi`.

## 증상

첫 자체 점검에서는 키가 없다고 표시되고, 안내 메시지에 나온 명령어를 실행하면 실패합니다.

```text theme={null}
% npx apiyi@latest check
status:   no_key
node:     api.apiyi.com
hint:     No API key found. Copy one at https://api.apiyi.com/token, then run "apiyi auth set-key" or export APIYI_API_KEY.

% apiyi auth set-key
zsh: command not found: apiyi
```

Windows에서는 표현이 다릅니다(예: “apiyi”는 cmdlet의 이름으로 인식되지 않습니다). 하지만 원인은 동일합니다.

## 원인

`npx`는 npm의 임시 캐시에서 CLI를 실행하며 **`apiyi`를 PATH에 추가하지 않습니다**. 0.2.1 이하 버전에서는 힌트에 짧은 형식인 `apiyi auth set-key`를 사용했기 때문에, 이를 복사하면 바로 이 오류가 발생했습니다.

**0.2.2**부터 CLI는 `npx`를 통해 실행되는 경우 이를 감지하고 힌트에 전체 형식인 `npx apiyi@latest auth set-key`를 표시합니다. `--help`에도 이 내용이 설명되어 있습니다.

## 수정

<Tabs>
  <Tab title="npx를 계속 사용합니다(권장, 설치할 항목 없음)">
    모든 명령 앞에 `npx apiyi@latest`를 붙입니다. 항상 최신 버전을 사용하며 컴퓨터에 아무것도 남지 않습니다.

    ```bash theme={null}
    npx apiyi@latest auth set-key
    npx apiyi@latest check
    npx apiyi@latest chat "Hello" -m gpt-5.4-mini
    ```
  </Tab>

  <Tab title="한 번 전역으로 설치합니다">
    설치한 후에는 `apiyi`만 입력하면 됩니다.

    ```bash theme={null}
    npm i -g apiyi
    apiyi auth set-key
    apiyi check
    ```

    나중에 업그레이드하려면 `npm i -g apiyi@latest`을 실행합니다.
  </Tab>

  <Tab title="환경 변수를 사용합니다">
    설정 파일에 저장되지 않으며 현재 터미널에만 적용됩니다.

    ```bash theme={null}
    export APIYI_API_KEY=sk-your-apiyi-key
    npx apiyi@latest check
    ```

    계속 적용하려면 `export` 줄을 `~/.zshrc`(또는 `~/.bashrc`)에 추가합니다.
  </Tab>
</Tabs>

## 최초 설정 단계별 안내

<Steps>
  <Step title="키 복사">
    [token 페이지](https://api.apiyi.com/token)를 열고 `sk-`로 시작하는 token을 복사합니다. token이 없다면 먼저 하나 만듭니다.
  </Step>

  <Step title="키 저장">
    `npx apiyi@latest auth set-key`를 실행합니다. `API key (input hidden):`이 표시되면 키를 붙여넣고 Enter를 누릅니다.
    입력하거나 붙여넣는 동안 화면에 아무것도 표시되지 않습니다. 다른 사람이 어깨너머로 키를 볼 수 없도록 의도된 동작입니다.
    `Saved apiKey to ~/.config/apiyi/config.json (mode 0600)`이 표시되면 완료된 것입니다.
  </Step>

  <Step title="다시 확인">
    `npx apiyi@latest check`을 실행합니다. `ok`의 `status`가 표시되면 키가 유효하고 노드에 연결할 수 있다는 뜻입니다.
  </Step>

  <Step title="첫 메시지 보내기">
    `npx apiyi@latest chat "Hello" -m gpt-5.4-mini`을 실행합니다. 응답과 token 사용량이 표시되면 모든 것이 정상적으로 작동하는 것입니다.
  </Step>
</Steps>

## 자주 묻는 질문

<AccordionGroup>
  <Accordion title="키를 붙여 넣어도 화면에 아무것도 표시되지 않습니다. 붙여 넣어진 건가요?">
    입력 내용은 숨겨져 있습니다. 붙여 넣은 후 Enter 키를 누르기만 하면 됩니다. 다시 확인하려면 `npx apiyi@latest auth show`을 실행합니다. 저장된 키가 마스킹되어 출력됩니다.
  </Accordion>

  <Accordion title="npm i -g apiyi를 실행했는데도 command not found가 표시됩니다">
    npm의 전역 디렉터리가 PATH에 없습니다. `npm prefix -g`을 실행해 디렉터리를 확인한 다음, `bin` 하위 디렉터리를 PATH에 추가하고(`~/.zshrc`에서) 새 터미널을 엽니다. nvm으로 Node를 관리하는 경우 Node 버전을 전환하면 새 버전에서 전역 패키지도 다시 설치해야 합니다.
  </Accordion>

  <Accordion title="키는 어디에 저장되며, 어떻게 삭제하나요?">
    `~/.config/apiyi/config.json`에 저장되며, 파일 권한은 0600으로 설정되어 있어 사용자 본인만 읽을 수 있습니다. `npx apiyi@latest auth clear`을 실행해 삭제합니다.
  </Accordion>

  <Accordion title="Node 버전이 너무 오래되었다고 표시됩니다">
    CLI를 사용하려면 Node 18.17 이상이 필요합니다. `node -v`을 실행해 버전을 확인하고, 더 낮은 버전이라면 Node를 업그레이드합니다.
  </Accordion>

  <Accordion title="잔액을 확인할 때도 no_key 또는 permission denied가 표시됩니다">
    일반 `sk-` 키로는 잔액을 확인할 수 없습니다. 잔액을 확인하려면 `nap_`으로 시작하는 개인 액세스 token이 필요합니다. `npx apiyi@latest auth set-key --access-token`. [개인 액세스 token이란 무엇인가요?](/ko/faq/personal-access-token)를 참조하세요.
  </Accordion>
</AccordionGroup>

## 관련 문서

<CardGroup cols={2}>
  <Card title="AI 개발 키트 · CLI" icon="terminal" href="/ko/developer-kit#cli">
    모든 명령어, 키 조회 순서 및 종료 코드
  </Card>

  <Card title="API 키가 유효하지 않으면 어떻게 해야 하나요?" icon="key" href="/ko/faq/invalid-api-key">
    `check`이 invalid\_key를 반환할 때 이 문서를 확인하세요
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.