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

# news

> Complete reference for *kagi* news command - fetch Kagi News from public JSON endpoints with category and content filtering.

# `kagi news`

Read Kagi News from the public JSON endpoints. This command requires no authentication and provides access to Kagi's curated news feed.

<img src="https://mintcdn.com/kagi-cli/azau7DEucCKj5AfG/images/demos/news.gif?s=6ab088d39fbebddb91d137c74ef19229" alt="News demo" width="789" height="450" data-path="images/demos/news.gif" />

## Synopsis

```bash theme={null}
kagi news [OPTIONS]
```

## Description

The `kagi news` command fetches the latest news from Kagi's public news endpoints. Unlike search commands, this requires no authentication and can be used immediately after installation.

Kagi News provides a curated selection of important stories across various categories, updated throughout the day. You can also apply local content filters with built-in presets or custom keywords before the CLI emits JSON.

## Authentication

**Required:** None

This command works without any tokens, making it ideal for:

* Testing your installation
* Daily news briefings
* Public information gathering
* Unauthenticated environments

## Options

### `--category <CATEGORY>`

News category to fetch.

**Default:** `world`

**Available Categories:** use `kagi news --list-categories` to inspect the live category inventory. The available set changes over time and may include both core and community categories.

**Example:**

```bash theme={null}
kagi news --category tech
kagi news --category business --limit 5
```

### `--limit <COUNT>`

Number of stories to return.

**Type:** Integer
**Default:** 12
**Constraint:** must be greater than 0

**Example:**

```bash theme={null}
kagi news --limit 5
kagi news --category tech --limit 10
```

### `--lang <LANG>`

Language for news content.

**Default:** `default` (uses Kagi's default)
**Values:** Language codes as supported

**Example:**

```bash theme={null}
kagi news --lang en
```

### `--list-categories`

List available news categories instead of fetching news.

**Example:**

```bash theme={null}
kagi news --list-categories
```

Output shows available categories and their descriptions.

### `--chaos`

Get the current Kagi News chaos index.

The chaos index measures the level of disruption and uncertainty in current news cycles.

**Example:**

```bash theme={null}
kagi news --chaos
```

### `--list-filter-presets`

List built-in content-filter presets instead of fetching stories.

**Example:**

```bash theme={null}
kagi news --list-filter-presets
kagi news --list-filter-presets --lang en | jq '.presets[].id'
```

### `--filter-preset <PRESET_ID>`

Apply a built-in content-filter preset. Repeat the flag to combine multiple presets.

Use `kagi news --list-filter-presets` to inspect available ids.

**Example:**

```bash theme={null}
kagi news --filter-preset politics
kagi news --filter-preset politics --filter-preset conflicts
```

### `--filter-keyword <KEYWORD>`

Apply a custom filter keyword. Repeat the flag to combine multiple keywords.

**Example:**

```bash theme={null}
kagi news --filter-keyword trump
kagi news --filter-keyword trump --filter-keyword election
```

### `--filter-mode <MODE>`

How to handle matching stories.

**Default:** `hide`
**Values:** `hide`, `blur`

* `hide` removes matching stories from `.stories`
* `blur` keeps matching stories in `.stories` and tags them with `_content_filter`

**Example:**

```bash theme={null}
kagi news --filter-preset politics --filter-mode blur
```

### `--filter-scope <SCOPE>`

Which story fields to inspect for keyword matches.

**Default:** `all`
**Values:** `title`, `summary`, `all`

* `title` checks title and category
* `summary` checks `short_summary`
* `all` also checks perspectives, source names, story domains, and article links/domains

**Example:**

```bash theme={null}
kagi news --filter-keyword trump --filter-scope title
```

## Output Format

### News Response

```json theme={null}
{
  "latest_batch": {
    "id": "batch-123",
    "created_at": "2026-03-16T00:00:00Z"
  },
  "category": {
    "category_id": "tech",
    "category_name": "Technology"
  },
  "stories": [],
  "total_stories": 20,
  "domains": [],
  "read_count": 1234,
  "content_filter": {
    "mode": "blur",
    "scope": "all",
    "active_presets": ["politics"],
    "custom_keywords": ["trump"],
    "active_keywords": ["trump", "election"],
    "filtered_count": 1
  }
}
```

### Fields

| Field            | Type    | Description                                   |
| ---------------- | ------- | --------------------------------------------- |
| `latest_batch`   | object  | Metadata for the current news batch           |
| `category`       | object  | Resolved category metadata                    |
| `stories`        | array   | Raw story payloads returned by Kagi News      |
| `total_stories`  | integer | Total number of stories in the category       |
| `domains`        | array   | Domain-level metadata from the feed           |
| `read_count`     | integer | Aggregate read count for the category         |
| `content_filter` | object  | Present when local content filters are active |

### Filter Preset Response

```json theme={null}
{
  "language": "en",
  "presets": [
    {
      "id": "politics",
      "label": "Politics",
      "keywords": ["trump", "biden", "election"]
    }
  ]
}
```

## Examples

### Basic Usage

```bash theme={null}
# Get world news (default)
kagi news

# Get tech news
kagi news --category tech

# Get 5 business stories
kagi news --category business --limit 5
```

### Content Filtering

```bash theme={null}
# Hide stories that match the built-in politics preset
kagi news --filter-preset politics

# Keep matching stories, but tag them for downstream tooling
kagi news --filter-preset politics --filter-mode blur

# Filter with custom keywords only
kagi news --filter-keyword trump --filter-keyword election

# Limit matching to title/category checks
kagi news --filter-keyword trump --filter-scope title
```

### Processing Output

```bash theme={null}
# Inspect the story payloads
kagi news | jq '.stories'

# Read category metadata
kagi news | jq '.category'

# Read the latest batch metadata
kagi news | jq '.latest_batch'

# Save to file
kagi news --category tech > tech-news.json

# Inspect active content-filter metadata
kagi news --filter-preset politics | jq '.content_filter'

# See which stories were tagged in blur mode
kagi news --filter-preset politics --filter-mode blur \
  | jq '.stories[] | select(._content_filter != null) | {title, _content_filter}'
```

### Daily Briefing

```bash theme={null}
#!/bin/bash
# Daily news briefing script

echo "📰 Today's News"
echo "==============="
for category in tech business science; do
  echo ""
  echo "${category^^}:"
  kagi news --category "$category" --limit 3 | jq '.stories'
done
```

### Chaos Index

```bash theme={null}
# Check current news chaos level
kagi news --chaos
```

## Exit Codes

| Code | Meaning                        |
| ---- | ------------------------------ |
| 0    | Success                        |
| 1    | Error (network, parsing, etc.) |

## Troubleshooting

### Empty results

* Try different category
* Check whether local content filters removed every story
* Check network connectivity
* Verify Kagi endpoints are accessible

### "Failed to fetch"

* Check internet connection
* Verify DNS resolution: `nslookup kagi.com`
* Try with curl: `curl https://kagi.com`

## See Also

* [smallweb](/commands/smallweb) - Kagi Small Web feed
* [Workflows](/guides/workflows) - News automation patterns