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

# Gumloop for Terminal

> Drive Gumloop agents, sessions, chat completions, MCP servers, skills, and artifacts from your shell.

`gumloop` is the command line for Gumloop. Sign in once, then drive your agents, sessions, chat completions, MCP integrations, skills, and artifacts from the terminal. Every command has a `--json` mode so you can pipe results into scripts, cron jobs, or any other tool you already use.

## Install

The CLI is the same package as the [Python SDK](/api-reference/sdk/python). Install it however you prefer — for a global, isolated install (recommended) use `uv` or `pipx`:

<CodeGroup>
  ```bash uv theme={"dark"}
  uv tool install gumloop
  ```

  ```bash pipx theme={"dark"}
  pipx install gumloop
  ```

  ```bash pip theme={"dark"}
  pip install gumloop
  ```
</CodeGroup>

Verify the install:

```bash theme={"dark"}
gumloop --version
```

<Note>
  The Gumloop CLI runs on **macOS** and **Linux** (including WSL). It is not supported on native Windows because credential storage and the OAuth callback server rely on POSIX-only paths. The Python SDK itself works on Windows — import `from gumloop import Gumloop` directly.
</Note>

### Linux prerequisites

The CLI stores credentials in your OS keychain. macOS Keychain is always available, but on Linux you need one of:

```bash theme={"dark"}
sudo apt install gnome-keyring libsecret-1-0
sudo apt install kwalletmanager
```

On a headless box without a keychain, skip `gumloop login` entirely and pass credentials per invocation via [environment variables](/cli/authentication#environment-variables).

## Sign in

```bash theme={"dark"}
gumloop login
```

Pick **OAuth (browser)** at the prompt. The CLI opens your browser, you click "Allow" on the Gumloop consent screen, and you're signed in. Tokens are stored in your OS keychain and the CLI refreshes them for you when they expire.

Prefer an API key, or running on a headless box? See [Authentication](/cli/authentication).

## Your first command

List the agents you can see:

```bash theme={"dark"}
gumloop agents list
```

```text theme={"dark"}
ID                NAME                MODEL                       TEAM            ACTIVE
agent_g6f1a2b3    Sales research      anthropic/claude-sonnet-4   team_4f8c92ab   yes
agent_h7e9c1d4    Support triage      openai/gpt-5                team_4f8c92ab   yes
```

Grab an ID from that table and start a chat:

```bash theme={"dark"}
gumloop sessions create agent_g6f1a2b3 --input "Summarize this week's pipeline."
```

That's it. From here, every command works the same way — `gumloop <thing> <action>`, with `--help` on anything to see all the flags.

## Commands

| Command                                                                               | What it does                                                                       |
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [`gumloop login`](/cli/authentication#login) / [`logout`](/cli/authentication#logout) | Manage stored credentials                                                          |
| [`gumloop agents`](/cli/agents)                                                       | List, inspect, create, and update agents                                           |
| [`gumloop sessions`](/cli/sessions)                                                   | Create, inspect, send messages to, and cancel agent sessions                       |
| [`gumloop chat`](/cli/chat)                                                           | Send chat completions to any supported model (unary, streaming, structured, image) |
| [`gumloop mcp`](/cli/mcp)                                                             | Explore connected MCP servers and execute their tools                              |
| [`gumloop skills`](/cli/skills)                                                       | List, upload, update, and download skill files                                     |
| [`gumloop artifacts`](/cli/artifacts)                                                 | List and download artifacts produced by agents                                     |

## Global flags

These work on every command:

| Flag              | Env var            | Description                                                         |
| ----------------- | ------------------ | ------------------------------------------------------------------- |
| `--team-id`       | `GUMLOOP_TEAM_ID`  | Scope the command to a single team (workspace).                     |
| `--base-url`      | `GUMLOOP_BASE_URL` | Override the Gumloop API base URL (useful for self-hosted/staging). |
| `--version`, `-V` | —                  | Print the CLI version and exit.                                     |
| `--help`, `-h`    | —                  | Show contextual help for any command or subcommand.                 |

Most subcommands additionally accept `--json` to print the raw response payload instead of the human-friendly table, which is handy for piping into `jq`, scripts, or other tools.