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

# CLI

> Install the MKA1 Code CLI, run interactive sessions, and use coding tasks in scripts.

export const ScreenshotCrop = ({src, alt, width, height, x = 0, y = 0, cropWidth = width, cropHeight = height, maxWidth = "100%"}) => <div className="not-prose" style={{
  position: "relative",
  overflow: "hidden",
  width: "100%",
  maxWidth,
  margin: "0 auto",
  aspectRatio: `${cropWidth} / ${cropHeight}`
}}>
    <img src={src} alt={alt} width={width} height={height} style={{
  position: "absolute",
  display: "block",
  margin: 0,
  maxWidth: "none",
  width: `${width / cropWidth * 100}%`,
  height: "auto",
  left: `${-x / cropWidth * 100}%`,
  top: `${-y / cropHeight * 100}%`
}} />
  </div>;

The MKA1 Code CLI runs the coding agent in your terminal. Its executable is `mka1-code`; the [MKA1 API CLI](/docs/cli/introduction) uses `mka1` to call API operations.

## Install the CLI

On macOS, Linux, or WSL, run the install script in a terminal:

```bash Bash theme={null}
curl -fsSL https://downloads.mka1.com/code/install.sh | bash
```

The script selects the build for your processor, verifies its checksum, and installs `mka1-code` in `~/.local/bin` without `sudo`. It does not change your shell configuration. If that folder is not on your `PATH`, the script prints an `export PATH` line to add to your shell's startup file, such as `~/.zshrc` for Zsh or `~/.bashrc` for Bash.

Open a new terminal and confirm that the CLI runs:

```bash CLI theme={null}
mka1-code --version
```

To update the CLI, run the install script again. To install it in another folder, set `MKA1_INSTALL_DIR`:

```bash Bash theme={null}
curl -fsSL https://downloads.mka1.com/code/install.sh | MKA1_INSTALL_DIR="$HOME/bin" bash
```

### Install a downloaded package

On Windows, or to install your organization's distribution, download the CLI package and install it yourself. For an organization distribution, follow the [organization download steps](/docs/mka1-code/install#organization-distributions) and choose the CLI package. Otherwise, download the package for your operating system and processor. These links point to MKA1 Code 1.57.4.

| Platform | Download |
| - | - |
| macOS · Apple silicon | [Download CLI](https://downloads.mka1.com/code/v1.57.4/mka1-code-cli-1.57.4-darwin-arm64) |
| macOS · Intel | [Download CLI](https://downloads.mka1.com/code/v1.57.4/mka1-code-cli-1.57.4-darwin-x64) |
| Windows · x64 | [Download CLI](https://downloads.mka1.com/code/v1.57.4/mka1-code-cli-1.57.4-win32-x64.exe) |
| Linux · ARM64 | [Download CLI](https://downloads.mka1.com/code/v1.57.4/mka1-code-cli-1.57.4-linux-arm64) |
| Linux · x64 | [Download CLI](https://downloads.mka1.com/code/v1.57.4/mka1-code-cli-1.57.4-linux-x64) |

<Tabs>
  <Tab title="macOS / Linux">
    Open a terminal in the folder containing the downloaded executable. Replace `<downloaded-file>` with its exact filename, then copy it into a user-owned command directory:

    ```bash CLI theme={null}
    mkdir -p "$HOME/.local/bin"
    cp "<downloaded-file>" "$HOME/.local/bin/mka1-code"
    chmod +x "$HOME/.local/bin/mka1-code"
    export PATH="$HOME/.local/bin:$PATH"
    mka1-code --help
    ```

    The final command should display CLI help. The `export` applies to this terminal only. To use the CLI in new terminals, add the same `export PATH` line to your shell's startup file, such as `~/.zshrc` for Zsh or `~/.bashrc` for Bash.
  </Tab>

  <Tab title="Windows">
    1. Create a folder for the CLI, such as `%LOCALAPPDATA%\MKA1Code\bin`.
    2. Move the downloaded executable into it and rename the file to `mka1-code.exe`.
    3. Add that folder to your user `Path` environment variable, then open a new PowerShell window.
    4. Run `mka1-code --help`. It should display CLI help. If the command is not found, check that `Path` contains the folder, not the executable's full path.
  </Tab>
</Tabs>

## Sign in and start a session

After installing the executable, open a terminal in your project directory, sign in, and start an interactive session:

```bash CLI theme={null}
mka1-code login
mka1-code doctor
mka1-code
```

Check the individual results from `doctor` before starting work; it identifies account, model-catalog, runtime, and connector problems.

Describe a task in the terminal, follow the agent's progress, and respond to questions or approval requests. Use `/model` to select a model, `@` to reference project files, `/attach <path>` to attach an image, and `/sessions` to find previous work. Use `/help` to see the available interactive commands.

To resume work, find its identifier with `/sessions` and pass it to `--resume`:

```bash CLI theme={null}
mka1-code --resume <session-id>
```

<Frame caption="The /help output lists commands for agents, account access, usage, plugins, and diagnostics.">
  <ScreenshotCrop src="/images/mka1-code/guides/cli.jpg" alt="CLI help showing available slash commands" width={1265} height={712} x={30} y={50} cropWidth={900} cropHeight={360} maxWidth="100%" />
</Frame>

## Run a task from a script

For a single task, use `run`:

```bash CLI theme={null}
mka1-code run "Read README.md and identify how to run this project and its tests. Do not change files."
```

Add `--output-format json` when another program needs to consume the result. The CLI returns one result object after the run finishes:

```bash CLI theme={null}
mka1-code run --output-format json "Read checkout.js and explain how item quantities affect the total. Do not change files."
```

A noninteractive run has no way to answer an approval request or clarifying question. The CLI refuses a request that needs that interaction instead of waiting indefinitely, so use an interactive session for work that needs your decisions. Scripts should inspect the result status and exit code before treating the task as successful.

## Find models and previous sessions

Use these commands outside the interactive screen when you need to inspect setup or choose a saved session:

```bash CLI theme={null}
mka1-code whoami
mka1-code models --refresh
mka1-code sessions
```

`whoami` identifies the active account. `models --refresh` reloads the gateway catalog. `sessions` lists recent sessions; add `--all` to include older ones or `--json` for structured output. Use the displayed session ID with `--resume` to continue the intended conversation.

In an interactive session, `/plan` controls planning and `/permissions` selects the approval policy. `/compact` summarizes older history, while `/usage` shows usage. Use `Ctrl + C` to stop an active turn; when idle, the CLI asks whether you want to exit. `/exit` closes the interface.

## Choose an output format

| Format | Behavior | Use it for |
| - | - | - |
| `text` | Prints the response as text. | Reading the result in a terminal. |
| `json` | Writes a result object when the run ends. | Processing a completed task. |
| `stream-json` | Emits one JSON record per line during execution and a final result. | Following progress from another program. |

Diagnostic errors go to standard error. Keep those separate from structured standard output when integrating the CLI into a script. A final response alone is not proof that a test passed: inspect the task status and the reported command result.

For a prompt stored in a file, use standard input:

```bash CLI theme={null}
mka1-code run - < task.txt
```

Put the complete request in `task.txt`, including its project assumptions and expected output. Run the command from the intended project directory.

Continue with [Usage and troubleshooting](/docs/mka1-code/troubleshooting).