> ## 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 是臨時執行，不會安裝 apiyi 命令。後續命令都帶上 npx apiyi@latest 字首，或用 npm i -g apiyi 裝一次。

## 簡短回答

`npx apiyi@latest` 是**臨時下載、跑完即走**，不會在電腦上留下一個 `apiyi` 命令。所以接下來的每條命令都要寫成 `npx apiyi@latest …`，例如儲存 Key：

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

想以後直接敲 `apiyi`，就全域性安裝一次：`npm i -g apiyi`。

## 問題現象

第一次執行自檢，提示沒有 Key，照著提示敲命令卻報錯：

```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` 會把 CLI 下載到 npm 的臨時快取裡執行，**不會把 `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 "你好" -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="複製 Key">
    開啟 [令牌頁面](https://api.apiyi.com/token)，複製一個以 `sk-` 開頭的令牌；沒有就先新建一個。
  </Step>

  <Step title="儲存 Key">
    執行 `npx apiyi@latest auth set-key`，出現 `API key (input hidden):` 後貼上並回車。
    輸入時螢幕上不顯示任何字元，這是為了防止 Key 被旁人看到，屬於正常現象。
    看到 `Saved apiKey to ~/.config/apiyi/config.json (mode 0600)` 就是成功了。
  </Step>

  <Step title="重新自檢">
    執行 `npx apiyi@latest check`，`status` 顯示 `ok` 說明 Key 有效、節點連通。
  </Step>

  <Step title="發第一條訊息">
    執行 `npx apiyi@latest chat "你好" -m gpt-5.4-mini`，能看到回覆和 token 用量就全部跑通了。
  </Step>
</Steps>

## 常見問題

<AccordionGroup>
  <Accordion title="貼上 Key 時螢幕沒有任何反應，是不是沒粘上？">
    是隱藏輸入，粘貼後直接回車即可。不放心可以用 `npx apiyi@latest auth show` 檢視，會打碼顯示已儲存的 Key。
  </Accordion>

  <Accordion title="已經 npm i -g apiyi 了，還是 command not found？">
    說明 npm 的全域性目錄不在 PATH 裡。執行 `npm prefix -g` 看全域性目錄，把它下面的 `bin` 子目錄加進 PATH（寫進 `~/.zshrc`），然後重開終端。用 nvm 管理 Node 時，切換 Node 版本後也需要在新版本下重新全域性安裝。
  </Accordion>

  <Accordion title="Key 存在哪裡？怎麼刪除？">
    儲存在 `~/.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 或權限不足？">
    普通 `sk-` Key 讀不到餘額，查餘額要用個人訪問令牌（`nap_` 開頭）：`npx apiyi@latest auth set-key --access-token`。詳見 [什麼是個人訪問令牌？](/zh-Hant/faq/personal-access-token)
  </Accordion>
</AccordionGroup>

## 相關文件

<CardGroup cols={2}>
  <Card title="AI 開發者套件 · CLI 命令列" icon="terminal" href="/zh-Hant/developer-kit#cli-命令列">
    全部命令、Key 的查詢順序、退出碼
  </Card>

  <Card title="API Key 無效怎麼辦？" icon="key" href="/zh-Hant/faq/invalid-api-key">
    `check` 返回 invalid\_key 時看這裡
  </Card>
</CardGroup>


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