> ## 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.

# Why Does My Terminal Say apiyi Command Not Found?

> npx apiyi@latest runs the CLI without installing it, so there is no apiyi command afterwards. Keep the npx apiyi@latest prefix, or install once with npm i -g apiyi.

## Short Answer

`npx apiyi@latest` **downloads the CLI, runs it once and leaves nothing behind**, so no `apiyi` command is added to your machine. Every following command needs the full `npx apiyi@latest …` prefix, for example to save your key:

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

If you want to type plain `apiyi` from now on, install it globally once: `npm i -g apiyi`.

## Symptom

The first self-check says there is no key, and the command from the hint fails:

```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
```

On Windows the wording differs (for example "the term apiyi is not recognized as the name of a cmdlet"), but the cause is the same.

## Cause

`npx` runs the CLI from npm's temporary cache and **does not add `apiyi` to your PATH**. In version 0.2.1 and earlier, the hint used the short form `apiyi auth set-key`, so copying it led straight to this error.

From **0.2.2** on, the CLI detects when it runs through `npx` and prints the full form `npx apiyi@latest auth set-key` in its hints; `--help` explains this as well.

## Fix

<Tabs>
  <Tab title="Keep using npx (recommended, nothing to install)">
    Prefix every command with `npx apiyi@latest`. You always get the latest version and nothing stays on your machine:

    ```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="Install globally once">
    After installing, plain `apiyi` works:

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

    To upgrade later: `npm i -g apiyi@latest`.
  </Tab>

  <Tab title="Use an environment variable">
    Nothing is saved to a config file; it only applies to the current terminal:

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

    To keep it, add the `export` line to `~/.zshrc` (or `~/.bashrc`).
  </Tab>
</Tabs>

## First-Time Setup, Step by Step

<Steps>
  <Step title="Copy a key">
    Open the [token page](https://api.apiyi.com/token) and copy a token starting with `sk-`; create one first if you have none.
  </Step>

  <Step title="Save the key">
    Run `npx apiyi@latest auth set-key`. When you see `API key (input hidden):`, paste the key and press Enter.
    Nothing appears on screen while you type or paste. This is intentional, so nobody can read the key over your shoulder.
    `Saved apiKey to ~/.config/apiyi/config.json (mode 0600)` means it worked.
  </Step>

  <Step title="Check again">
    Run `npx apiyi@latest check`. A `status` of `ok` means the key is valid and the node is reachable.
  </Step>

  <Step title="Send your first message">
    Run `npx apiyi@latest chat "Hello" -m gpt-5.4-mini`. Seeing a reply and the token usage means everything works.
  </Step>
</Steps>

## Common Questions

<AccordionGroup>
  <Accordion title="Nothing happens on screen when I paste the key. Did it paste?">
    The input is hidden; just press Enter after pasting. To double-check, run `npx apiyi@latest auth show`, which prints the saved key masked.
  </Accordion>

  <Accordion title="I ran npm i -g apiyi and still get command not found">
    npm's global directory is not on your PATH. Run `npm prefix -g` to find it, add its `bin` subdirectory to PATH (in `~/.zshrc`), then open a new terminal. If you manage Node with nvm, switching Node versions also means installing globally again under the new version.
  </Accordion>

  <Accordion title="Where is the key stored, and how do I remove it?">
    In `~/.config/apiyi/config.json`, with file mode 0600 so only your user can read it. Remove it with `npx apiyi@latest auth clear`.
  </Accordion>

  <Accordion title="It says my Node version is too old">
    The CLI needs Node 18.17 or later. Run `node -v` to check, and upgrade Node if it is older.
  </Accordion>

  <Accordion title="Checking my balance also says no_key or permission denied">
    A regular `sk-` key cannot read the balance. Balance needs a personal access token (starting with `nap_`): `npx apiyi@latest auth set-key --access-token`. See [What Is a Personal Access Token?](/en/faq/personal-access-token)
  </Accordion>
</AccordionGroup>

## Related Docs

<CardGroup cols={2}>
  <Card title="AI Developer Kit · CLI" icon="terminal" href="/en/developer-kit#cli">
    All commands, key lookup order and exit codes
  </Card>

  <Card title="What If My API Key Is Invalid?" icon="key" href="/en/faq/invalid-api-key">
    Read this when `check` returns invalid\_key
  </Card>
</CardGroup>


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