kagi

command module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 1, 2025 License: MPL-2.0 Imports: 14 Imported by: 0

README

kagi

A fast, simple command-line interface for Kagi FastGPT - AI-powered search with web context.

Features

  • Simple Interface: Just type your query and get AI-powered answers
  • Multiple Output Formats: Plain text, Markdown, or JSON
  • Smart Color Output: Automatically detects terminals and pipes
  • Web References: Includes sources with every response
  • Flexible Input: Accept queries from arguments or stdin
  • AI Agent Friendly: Clean output formats for automation

Installation

Homebrew (Linux/macOS)
brew tap grantcarthew/tap
brew install grantcarthew/tap/kagi
Go Install
go install github.com/grantcarthew/kagi@latest
From Source
git clone https://github.com/grantcarthew/kagi.git
cd kagi
go build

Quick Start

1. Get a Kagi API Key
  1. Sign up at kagi.com
  2. Visit Account Settings > API
  3. Generate a FastGPT API key
2. Set Your API Key
export KAGI_API_KEY='your-api-key-here'

Add this to your ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish to make it permanent.

3. Ask Questions
kagi golang best practices

Usage

kagi [options] <query...>
Basic Examples
# Simple query
kagi what is kubernetes

# Multiple words automatically joined
kagi golang concurrency patterns

# With quotes (optional)
kagi "explain docker containers"
Output Formats
Text Format (Default)

Clean, readable output with numbered references:

$ kagi what is open source
**Open source** refers to software with source code that is freely available for anyone to inspect, modify, and enhance 【1】. With open source software (OSS), users may view, modify, adopt, and share the source code 【2】. Open source emphasizes collaboration and transparency, allowing users to view, modify, and share the software 【1】.

References:

1. What is open source? - https://opensource.com/resources/what-open-source - Open source software is software with source code that anyone can inspect, modify, and enhance. "Source code" is the part of software that most computer users ...
2. What is Open Source Software (OSS)? - https://github.com/resources/articles/what-is-open-source-software - Open source software (OSS) refers to software that features freely available source code, which users may view, modify, adopt, and share for ...
Markdown Format

Perfect for documentation or README files:

$ kagi --format md what is open source
# what is open source

**Open source** refers to software with source code that is freely available for anyone to inspect, modify, and enhance 【1】. With open source software (OSS), users may view, modify, adopt, and share the source code 【2】. Open source emphasizes collaboration and transparency, allowing users to view, modify, and share the software 【1】.

## References

1. [What is open source?](https://opensource.com/resources/what-open-source)
   > Open source software is software with source code that anyone can inspect, modify, and enhance. "Source code" is the part of software that most computer users ...
2. [What is Open Source Software (OSS)?](https://github.com/resources/articles/what-is-open-source-software)
   > Open source software (OSS) refers to software that features freely available source code, which users may view, modify, adopt, and share for ...
JSON Format

For scripting and automation:

$ kagi --format json what is open source
{
  "meta": {
    "id": "d598ad3c4d62f8a1319f999babff2c3e",
    "node": "australia-southeast1",
    "ms": 5
  },
  "data": {
    "output": "**Open source** refers to software with source code that is freely available for anyone to inspect, modify, and enhance 【1】. With open source software (OSS), users may view, modify, adopt, and share the source code 【2】. Open source emphasizes collaboration and transparency, allowing users to view, modify, and share the software 【1】.",
    "tokens": 0,
    "references": [
      {
        "title": "What is open source?",
        "snippet": "Open source software is software with source code that anyone can inspect, modify, and enhance. \"Source code\" is the part of software that most computer users ...",
        "url": "https://opensource.com/resources/what-open-source"
      },
      {
        "title": "What is Open Source Software (OSS)?",
        "snippet": "Open source software (OSS) refers to software that features freely available source code, which users may view, modify, adopt, and share for ...",
        "url": "https://github.com/resources/articles/what-is-open-source-software"
      }
    ]
  }
}
Using Stdin

Read queries from pipes or redirects:

# From echo
echo "explain kubernetes pods" | kagi

# From file
cat questions.txt | kagi

# From here-doc
kagi << EOF
What are the benefits of using Go for
backend development?
EOF

# In scripts
QUERY="golang vs rust performance"
echo "$QUERY" | kagi -f md > comparison.md
Common Options
# Quiet mode (output body only, no references)
kagi -q golang channels

# With heading (text format only)
kagi --heading golang best practices

# Markdown with quiet mode
kagi -f md -q golang testing > testing.md

# Increase timeout for complex queries
kagi --timeout 60 "comprehensive guide to kubernetes"

# Force color output in pipes
kagi --color always golang patterns | less -R

# Disable colors
kagi --color never golang patterns

# Debug mode
kagi --debug golang generics
Examples for Automation
# Save JSON response
kagi -f json "golang concurrency" > response.json

# Extract just the answer
kagi -q "what is docker" > answer.txt

# Generate markdown documentation
kagi -f md "golang error handling best practices" > errors.md

# Batch processing
cat topics.txt | while read topic; do
  kagi -f md -q "$topic" > "docs/${topic}.md"
done

# CI/CD usage
if kagi -q "is golang 1.23 stable"; then
  echo "Proceeding with upgrade"
fi

Command Reference

Options
Flag Short Default Description
--api-key $KAGI_API_KEY Kagi API key (overrides environment variable)
--format -f text Output format: text, txt, md, markdown, json
--quiet -q false Output only response body (no heading or references)
--heading false Include query as heading in text format
--timeout -t 30 HTTP request timeout in seconds
--color -c auto Color output: auto, always, never
--verbose false Output process information to stderr
--debug false Output detailed debug information to stderr
--version -v Display version information
--help -h Display help message
Environment Variables
Variable Description
KAGI_API_KEY Your Kagi API key (required unless using --api-key)
Exit Codes
Code Meaning
0 Success
1 Error (API error, network error, validation error)
130 Interrupted (Ctrl+C)

Color Output

The CLI automatically detects whether output is going to a terminal or pipe:

# Colored output (terminal)
kagi golang patterns

# No colors (piped)
kagi golang patterns | less

# Force colors in pipe
kagi --color always golang patterns | less -R

# Disable colors
kagi --color never golang patterns

Error Handling

Common Errors

Missing API Key:

$ kagi test
Error: API key required. Set KAGI_API_KEY environment variable or use --api-key flag

Empty Query:

$ kagi
Error: query cannot be empty

Invalid Format:

$ kagi -f xml test
Error: invalid format 'xml'. Valid formats: text, txt, md, markdown, json

API Error:

$ kagi test
Error: API error (401): Invalid or missing API key

Network Timeout:

$ kagi --timeout 1 test
Error: request timeout after 1s
Verbose Output

Use --verbose to see what's happening:

$ kagi --verbose golang channels
Querying Kagi FastGPT API...
Response received (1234ms)
[output...]
Debug Output

Use --debug for detailed information:

$ kagi --debug golang channels
Debug: API Key: ***
Debug: Query: golang channels
Debug: Format: text
Debug: Timeout: 30
Querying Kagi FastGPT API...
Response received (5ms)
[output...]

Troubleshooting

API Key Not Found

Make sure your API key is set:

echo $KAGI_API_KEY

If empty, add to your shell config:

# Bash/Zsh
echo 'export KAGI_API_KEY="your-key"' >> ~/.bashrc

# Fish
set -Ux KAGI_API_KEY "your-key"
Timeout Errors

Increase timeout for complex queries:

kagi --timeout 60 "your long query"
Color Output Issues

If colors appear broken:

# Disable colors
kagi --color never query
Rate Limiting

Kagi API has rate limits. If you receive a 429 error:

Error: API error (429): Rate limit exceeded. Please try again later.

Wait a few moments before retrying.

Development

Building
git clone https://github.com/grantcarthew/kagi.git
cd kagi
go build
Testing
# Run all tests
go test ./...

# With coverage
go test -cover ./...

# Verbose
go test -v ./...
Project Structure
kagi/
├── AGENTS.md          # AI agent context and development guide
├── CHANGELOG.md       # Version history and changes
├── CODE_OF_CONDUCT.md # Community guidelines
├── CONTRIBUTING.md    # Contribution guidelines
├── LICENSE            # Mozilla Public License 2.0
├── README.md          # This file
├── ROLE.md            # Role definition for AI agents
├── docs/              # Design decisions and task documentation
├── go.mod             # Go module definition
├── go.sum             # Dependency checksums
├── main.go            # All code (types, API client, CLI, formatting)
├── main_test.go       # Comprehensive test suite (83 tests)
└── test-interactive   # Interactive CLI testing script

The project follows the KISS principle with a flat structure - all code in a single main.go file.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Guidelines
  1. Follow Go conventions (gofmt, golint)
  2. Add tests for new features
  3. Update documentation
  4. Keep it simple (KISS principle)
Reporting Issues

Please include:

  • Operating system and version
  • Go version (go version)
  • Full command and error output
  • Expected vs actual behavior

Report issues at: https://github.com/grantcarthew/kagi/issues

License

Mozilla Public License 2.0 (MPL-2.0)

See LICENSE file for details.

Acknowledgments

Note: This is an unofficial tool and is not affiliated with or endorsed by Kagi.

Documentation

The Go Gopher

There is no documentation for this package.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.