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

# CLI

> How to use the Linkup CLI from your terminal and scripts.

## Introduction

The Linkup CLI is the official terminal client for Linkup. Use it to run [**Search**](/pages/documentation/endpoints/search/overview), [**Fetch**](/pages/documentation/endpoints/fetch/overview), [**Research**](/pages/documentation/endpoints/research/overview), and [**Tasks**](/pages/documentation/endpoints/tasks/overview) from your shell.

<CardGroup cols={2}>
  <Card title="Github" icon="github" href="https://github.com/LinkupPlatform/linkup-cli">
    Repository (feel free to contribute)
  </Card>

  <Card title="NPM" icon="npm" href="https://www.npmjs.com/package/linkup-search-cli">
    NPM page
  </Card>
</CardGroup>

## Quickstart

Get started with the Linkup CLI in less than 5 minutes.

<Card title="Get your API key" icon="key" href="https://app.linkup.so" horizontal="True">
  Create a Linkup account for free to get your API key.
</Card>

## Installation

Install the CLI globally from npm:

```shell theme={"system"}
npm install -g linkup-search-cli
```

The CLI requires Node.js `22` or newer.

## Authentication

Configure your API key once with the interactive setup flow:

```shell theme={"system"}
linkup setup
```

This saves your key to `~/.linkup/config`. For scripts, CI, or temporary sessions, set `LINKUP_API_KEY` instead:

```shell theme={"system"}
export LINKUP_API_KEY="your-api-key"
```

`LINKUP_API_KEY` takes precedence over the saved config file. Use `linkup config` to inspect the resolved configuration, and `linkup logout` to remove the saved key.

## Usage

The global `--json` flag prints raw JSON responses, which is useful for scripts and tools:

```shell theme={"system"}
linkup --json search "What is Linkup?"
```

Use `--help` on any command to see the full command-specific help.

### Search

Use `linkup search` to run an immediate web search. The short alias is `linkup s`.

```shell theme={"system"}
linkup search "What is Microsoft's 2024 revenue?" --depth deep
linkup search "latest AI search news" --output search-results --max-results 10
linkup search "company revenue" --output structured --schema-file schema.json
```

| Flag                | Values                                                 | Default            | Description                                                                         |
| ------------------- | ------------------------------------------------------ | ------------------ | ----------------------------------------------------------------------------------- |
| `--depth`, `-d`     | `"fast"`, `"standard"`, `"deep"`                       | `"standard"`       | Search depth.                                                                       |
| `--output`, `-o`    | `"sourced-answer"`, `"search-results"`, `"structured"` | `"sourced-answer"` | Output format.                                                                      |
| `--schema-file`     | File path                                              | None               | Path to a JSON schema file. Implies `--output structured` unless `--output` is set. |
| `--schema`          | JSON string                                            | None               | Inline JSON schema. Implies `--output structured` unless `--output` is set.         |
| `--include-domains` | Comma-separated domains                                | None               | Restrict results to specific domains.                                               |
| `--exclude-domains` | Comma-separated domains                                | None               | Exclude specific domains from results.                                              |
| `--from-date`       | Date string                                            | None               | Only include results published on or after this date.                               |
| `--to-date`         | Date string                                            | None               | Only include results published on or before this date.                              |
| `--include-images`  | Boolean flag                                           | `false`            | Request images in search results. Only used with `--output search-results`.         |
| `--max-results`     | Positive integer                                       | None               | Maximum number of search results. Only used with `--output search-results`.         |
| `--file`, `-f`      | File path                                              | None               | Read the query from a file.                                                         |
| `--async`           | Boolean flag                                           | `false`            | Run the search as an asynchronous task.                                             |
| `--wait`, `-w`      | Boolean flag                                           | `false`            | Wait for the asynchronous task to complete. Only used with `--async`.               |
| `--poll-interval`   | Seconds                                                | `5`                | Seconds between status checks when waiting.                                         |
| `--timeout`         | Seconds                                                | `1200`             | Maximum seconds to wait before giving up.                                           |

You can also pipe a query through stdin:

```shell theme={"system"}
echo "What is Linkup?" | linkup search
```

### Fetch

Use `linkup fetch` to extract a URL as markdown. The short alias is `linkup f`.

```shell theme={"system"}
linkup fetch https://example.com
linkup fetch https://example.com --render-js
linkup fetch https://example.com --include-raw-html --json
```

| Flag                 | Values       | Default  | Description                                                           |
| -------------------- | ------------ | -------- | --------------------------------------------------------------------- |
| `<url>`              | URL          | Required | URL to fetch.                                                         |
| `--render-js`        | Boolean flag | `false`  | Execute JavaScript before extracting content.                         |
| `--include-raw-html` | Boolean flag | `false`  | Include the raw HTML in the response output.                          |
| `--extract-images`   | Boolean flag | `false`  | Extract image metadata from the fetched page.                         |
| `--async`            | Boolean flag | `false`  | Run the fetch as an asynchronous task.                                |
| `--wait`, `-w`       | Boolean flag | `false`  | Wait for the asynchronous task to complete. Only used with `--async`. |
| `--poll-interval`    | Seconds      | `5`      | Seconds between status checks when waiting.                           |
| `--timeout`          | Seconds      | `1200`   | Maximum seconds to wait before giving up.                             |

### Research

Use `linkup research` to run a deep research task asynchronously. The short alias is `linkup r`.

```shell theme={"system"}
linkup research "State of the semiconductor market in 2026"
linkup research "State of the semiconductor market in 2026" --mode investigate --wait
linkup research "company revenue" --output structured --schema-file schema.json --wait
linkup research get <id>
linkup research list --page 1 --page-size 10
```

| Flag                | Values                                              | Default            | Description                                                                         |
| ------------------- | --------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------- |
| `--output`, `-o`    | `"sourced-answer"`, `"structured"`                  | `"sourced-answer"` | Output format.                                                                      |
| `--schema-file`     | File path                                           | None               | Path to a JSON schema file. Implies `--output structured` unless `--output` is set. |
| `--schema`          | JSON string                                         | None               | Inline JSON schema. Implies `--output structured` unless `--output` is set.         |
| `--mode`, `-m`      | `"answer"`, `"auto"`, `"investigate"`, `"research"` | None               | Research mode or effort profile.                                                    |
| `--reasoning-depth` | `"S"`, `"M"`, `"L"`, `"XL"`                         | `"L"`              | Reasoning depth within the selected mode.                                           |
| `--include-domains` | Comma-separated domains                             | None               | Restrict results to specific domains.                                               |
| `--exclude-domains` | Comma-separated domains                             | None               | Exclude specific domains from results.                                              |
| `--from-date`       | Date string                                         | None               | Only include results published on or after this date.                               |
| `--to-date`         | Date string                                         | None               | Only include results published on or before this date.                              |
| `--file`, `-f`      | File path                                           | None               | Read the query from a file.                                                         |
| `--wait`, `-w`      | Boolean flag                                        | `false`            | Wait for the task to complete and print the result.                                 |
| `--poll-interval`   | Seconds                                             | `5`                | Seconds between status checks when waiting.                                         |
| `--timeout`         | Seconds                                             | `1200`             | Maximum seconds to wait before giving up.                                           |

Use `linkup research get <id>` to fetch a research task by ID. Add `--wait` to poll until the task completes.

Use `linkup research list` to list recent research tasks. It supports `--page`, `--page-size`, `--sort-by`, and `--sort-direction`.

### Tasks

Use `linkup tasks` to create and manage asynchronous **Search**, **Fetch**, and **Research** tasks. The short alias is `linkup t`.

Create tasks from a JSON file or stdin:

```shell theme={"system"}
linkup tasks create --file tasks.json
cat tasks.json | linkup tasks create
linkup tasks create --file tasks.json --wait
```

Task JSON can be a single task request or an array of task requests using camelCase fields:

```json theme={"system"}
[
  {
    "type": "search",
    "input": {
      "query": "What is Linkup?",
      "depth": "standard",
      "outputType": "sourcedAnswer"
    }
  },
  {
    "type": "fetch",
    "input": {
      "url": "https://docs.linkup.so"
    }
  }
]
```

| Command                 | Flags                                                                          | Description                                              |
| ----------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------- |
| `linkup tasks create`   | `--file`, `--wait`, `--poll-interval`, `--timeout`                             | Create one or more asynchronous tasks from JSON.         |
| `linkup tasks get <id>` | `--wait`, `--poll-interval`, `--timeout`                                       | Fetch a task by ID, optionally polling until completion. |
| `linkup tasks list`     | `--page`, `--page-size`, `--status`, `--type`, `--sort-by`, `--sort-direction` | List recent tasks.                                       |

`linkup tasks list` supports task statuses `"pending"`, `"processing"`, `"completed"`, and `"failed"`, and task types `"search"`, `"fetch"`, and `"research"`.

## Asynchronous tasks

For `linkup search` and `linkup fetch`, add `--async` to enqueue the call as a task:

```shell theme={"system"}
linkup search "What is Linkup?" --async
linkup fetch https://example.com --async
```

Add `--wait` to poll until the task completes and print the result:

```shell theme={"system"}
linkup research "State of the semiconductor market in 2026" --wait
linkup tasks create --file tasks.json --wait
```

Waiting uses `--poll-interval 5` and `--timeout 1200` by default. If a wait times out, the task keeps running and the CLI prints a command you can run later to resume waiting.

## Scripting

Use `--json` with command-line tools such as `jq`:

```shell theme={"system"}
linkup --json research "State of the semiconductor market in 2026" --wait | jq ".output.answer"
```

You can combine `--json`, stdin, and file input to build repeatable scripts:

```shell theme={"system"}
echo "What is Linkup?" | linkup --json search | jq ".answer"
linkup --json tasks list --status pending,processing --type search,research
```

## Additional resources

### CLI changelog

Read the [CLI changelog](/pages/changelog/cli) for release notes.

### Endpoint guides

Use the endpoint guides to learn the API concepts behind each command: [**Search**](/pages/documentation/endpoints/search/overview), [**Fetch**](/pages/documentation/endpoints/fetch/overview), [**Research**](/pages/documentation/endpoints/research/overview), and [**Tasks**](/pages/documentation/endpoints/tasks/overview).

You're ready to use the Linkup CLI from your terminal.

<Info>
  **Need help?** Email `support@linkup.so`, ping us on [Discord](https://discord.com/invite/9q9mCYJa86), or [talk to us](https://calendar.app.google/zNUZz7RxgMMk9pKW7).
</Info>