kagi-cli 0.1.0

A command-line interface for Kagi.com's APIs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184

# kagi-api

Kagi API libraries and CLI written in Rust

## Using the kagi-api library

Add the following dependency:

```toml
[dependencies]
kagi-api = { version = "0.1" }
```

```rust
use kagi_api::v0::FastGPT;

#[tokio::main]
async fn main() {
    let config = kagi_api::KagiConfig::with_api_key("api key goes here");
    let client = kagi_api::KagiClient::new(config);

    let use_cache = true;
    let answer = client
        .fastgpt("How do I entertain my cat?", use_cache)
        .await
        .expect("A valid FastGPT search result");

    // FIXME: Cannot `.render()` without kagi-cli: Remove `Render` trait's coupling from `Args`.
    serde_json::to_writer_pretty(std::io::stdout(), &answer).unwrap();
}
```

See the [`kagi-api/examples`](./kagi-api/examples/) directory for more examples.

FIXME: Examples are still unstable, port more examples here when stable.

## Using the kagi-cli binary

Install from crates.io:

```sh
cargo install kagi-cli
```

Install from git:

```sh
git clone https://codeberg.org/synapse/kagi-api.git
cd kagi-api
cargo install --path kagi-cli
```

Install auto-completion, possibly replacing `zsh` with `bash`, `fish`, `powershell` or `elvish`:

```sh
source <(kagi-cli completion zsh)
```

Set an environment variable containing your API key.

Setting a logdir is optional and enables record-and-replay.

```sh
KAGI_API_KEY="api key goes here"
KAGI_API_LOGDIR="."
```

You can now query:

> ```sh
> $ kagi-cli fast-gpt 'How do I entertain my cat?'
> ```
>
> ```md
> There are several ways to **entertain your cat**:
>
> **Provide toys for playing**, such as balls, feathers on strings or catnip toys. **Interactive play sessions** can also stimulate cats. [1][2]
>
> **Hide treats and food around the house in puzzle feeders** or new locations. This provides mental enrichment. [1][3][4]
>
> **Inexpensive items like cardboard boxes** or empty paper towel rolls can be entertaining for cats to bat around or hide in. [1][5][2]
>
> **Cats may enjoy watching fish tanks or nature documentaries on TV.** [6][7]
>
> - 1. Puzzle feeders 2. Hide the food in new locations 3. Put food in a kitty KONG 4. Put kibble or treats inside an egg carton 5. Teach your cat some tricks 6. Searching for food scent Games 7. Make a labyrinth out of boxes [1]
>
> - Toys that keep your indoor cat entertained. How to entertain indoor cats: Providing a wide variety of cat toys will ensure your feline is never bored. (Image credit: Getty) Most vets recommend a minimum of 15-30 minutes of play per day, which is for both exercise and bonding. [2]
>
> - 4. jan. 2021 ... 6 Ways to Keep Your Cat Entertained · 1. Add a Furry Friend. Cats are social creatures, and the majority enjoy having a companion. · 2. Prepare a... [3]
>
> - If your feline friend is food motivated, then treat based puzzles can be a fun, low maintenance way of keeping your cat entertained (and fed). [4]
>
> - To keep a bored indoor cat entertained while you&#39;re not at home, open up some of your blinds and curtains so your cat can look out the window. You can also try leaving your TV on with a nature show playing to give your cat something to watch. [5]
>
> - 3. jul. 2023 ... You don't need to fork out for expensive toys though, a simple cardboard box can keep a moggie thoroughly entertained. They also like to play... [6]
>
> - Many cats love catnip, so you can buy catnip-filled toys or give your cat loose catnip to make play time extra fun. Multi-tiered cat trees, which you can build yourself or buy at pet stores, can give your kitty something fun to romp around on when you&#39;re not home. [7]
>
> [1]: https://www.meowsnpaws.com/cat-entertainment/how-to-entertain-cat/
> [2]: https://www.petsradar.com/advice/how-to-entertain-indoor-cats-and-keep-them-stimulated
> [3]: https://rufusandcoco.com.au/blogs/blog/6-ways-to-keep-your-cat-entertained
> [4]: https://www.petsecure.com.au/pet-care/10-ways-keep-cat-entertained-youre-house/
> [5]: https://www.wikihow.com/Keep-a-Bored-Indoor-Cat-Entertained-While-You%27re-Not-at-Home
> [6]: https://www.petsradar.com/advice/is-your-cat-bored-10-tips-to-entertain-your-moggy
> [7]: https://www.wikihow.com/Have-Fun-with-Your-Cat
> ```

Replaying the same request-response, but changing the output format:

> ```sh
> $ kagi-cli --replay -f json fast-gpt 'How do I entertain my cat?'
> ```
>
> ```json
> {
>   "meta": {
>     "id": "64872161-cae7-4ee0-a7b7-096f821bae75",
>     "node": "europe-west4",
>     "ms": 7512,
>     "api_balance": 0.0
>   },
>   "data": {
>     "output": "\nThere are several ways to **entertain your cat**:\n\n**Provide toys for playing**, such as balls, feathers on strings or catnip toys. **Interactive play sessions** can also stimulate cats. [1][2]\n\n**Hide treats and food around the house in puzzle feeders** or new locations. This provides mental enrichment. [1][3][4] \n\n**Inexpensive items like cardboard boxes** or empty paper towel rolls can be entertaining for cats to bat around or hide in. [1][5][2]\n\n**Cats may enjoy watching fish tanks or nature documentaries on TV.** [6][7]",
>     "tokens": 5921,
>     "references": [
>       {
>         "title": "50 Ways to Entertain Your Cat (+ Free PDF Printable)",
>         "snippet": "1. Puzzle feeders 2. Hide the food in new locations 3. Put food in a kitty KONG 4. Put kibble or treats inside an egg carton 5. Teach your cat some tricks 6. Searching for food scent Games 7. Make a labyrinth out of boxes",
>         "url": "https://www.meowsnpaws.com/cat-entertainment/how-to-entertain-cat/"
>       },
>       {
>         "title": "How to entertain indoor cats | PetsRadar",
>         "snippet": "Toys that keep your indoor cat entertained. How to entertain indoor cats: Providing a wide variety of cat toys will ensure your feline is never bored. (Image credit: Getty) Most vets recommend a minimum of 15-30 minutes of play per day, which is for both exercise and bonding.",
>         "url": "https://www.petsradar.com/advice/how-to-entertain-indoor-cats-and-keep-them-stimulated"
>       },
>       {
>         "title": "6 Ways to Keep Your Cat Entertained – Rufus & Coco Australia",
>         "snippet": "4. jan. 2021 ... 6 Ways to Keep Your Cat Entertained · 1. Add a Furry Friend. Cats are social creatures, and the majority enjoy having a companion. · 2. Prepare a...",
>         "url": "https://rufusandcoco.com.au/blogs/blog/6-ways-to-keep-your-cat-entertained"
>       },
>       {
>         "title": "10 Ways to Keep Your Cat Entertained While You're Out of the House",
>         "snippet": "If your feline friend is food motivated, then treat based puzzles can be a fun, low maintenance way of keeping your cat entertained (and fed).",
>         "url": "https://www.petsecure.com.au/pet-care/10-ways-keep-cat-entertained-youre-house/"
>       },
>       {
>         "title": "3 Ways to Keep a Bored Indoor Cat Entertained While You're ... - wikiHow",
>         "snippet": "To keep a bored indoor cat entertained while you&#39;re not at home, open up some of your blinds and curtains so your cat can look out the window. You can also try leaving your TV on with a nature show playing to give your cat something to watch.",
>         "url": "https://www.wikihow.com/Keep-a-Bored-Indoor-Cat-Entertained-While-You%27re-Not-at-Home"
>       },
>       {
>         "title": "Is your cat bored? | PetsRadar",
>         "snippet": "3. jul. 2023 ... You don't need to fork out for expensive toys though, a simple cardboard box can keep a moggie thoroughly entertained. They also like to play...",
>         "url": "https://www.petsradar.com/advice/is-your-cat-bored-10-tips-to-entertain-your-moggy"
>       },
>       {
>         "title": "How to Have Fun with Your Cat (with Pictures) - wikiHow",
>         "snippet": "Many cats love catnip, so you can buy catnip-filled toys or give your cat loose catnip to make play time extra fun. Multi-tiered cat trees, which you can build yourself or buy at pet stores, can give your kitty something fun to romp around on when you&#39;re not home.",
>         "url": "https://www.wikihow.com/Have-Fun-with-Your-Cat"
>       }
>     ]
>   }
> }
> ```

FIXME: Improve `cargo install kagi-cli` installation instructions when crate lands on crates.io.

FIXME: Provide examples as Rustdoc and export them here programmatically (one source, testable).

## Contributing

To contribute, install the Rust toolchain, e.g. using [rustup][rustup]:

```sh
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
```

[rustup]: https://rustup.rs/

Fork the workspace containing library and CLI code:

```
git clone https://codeberg.org/synapse/kagi-api.git
```