# Getting Started

Getting Started

## Overview

`bookstack-cli-rs` is a command-line interface for the BookStack API, written in Rust. It supports profile-based authentication, all CRUD operations for books/chapters/pages/shelves, and full-text search. Container filtering lets you narrow list results by shelf (books), book (chapters), or book/chapter (pages).

## Installation

### From Source

```bash
cargo install --path .
```

### Pre-built Binaries

Download from Gitea generic packages:

```bash
curl -fsSL \
  --user "<username>:$GITEA_TOKEN" \
  https://git.example.com/api/packages/<owner>/generic/bookstack-cli-rs/v0.2.0/bookstack-cli-rs-x86_64-unknown-linux-gnu \
  -o bookstack-cli-rs && chmod +x bookstack-cli-rs
```

### Version

Current version: **v0.2.0**

## Configuration

Profiles store your BookStack instance URL and API tokens. Config is saved to `~/.config/bookstack-cli-rs/profiles.toml`.

### Add a Profile (CLI)

```bash
bookstack profiles add --name mywiki \
  --url https://wiki.example.com \
  --token-id ABCDEF1234567890 \
  --token-secret 0123456789ABCDEF
```

### Add a Profile (Environment Variables)

```bash
export BOOKSTACK_URL=https://wiki.example.com
export BOOKSTACK_TOKEN_ID=ABCDEF1234567890
export BOOKSTACK_TOKEN_SECRET=0123456789ABCDEF

bookstack profiles add --name mywiki
```

### List Profiles

```bash
bookstack profiles list
```

Output:

```
Configured profiles:
  [default] My Wiki - https://wiki.example.com (default)
  [mywiki] Another Wiki - https://wiki2.example.com
```

### Delete a Profile

```bash
bookstack profiles delete --name mywiki
```

## Using Profiles

Specify which profile to use with `-p` or `--profile`:

```bash
bookstack -p mywiki list-books
bookstack list-books                    # uses default profile if no -p given
```

## Basic Usage Examples

### List All Books

```bash
bookstack list-books
```

### Filter Books by Shelf

```bash
bookstack list-books --shelf-id 1
```

### List Chapters in a Book

```bash
bookstack list-chapters --book-id 9
```

### List Pages in a Chapter

```bash
bookstack list-pages --chapter-id 42
```

### Search Content

```bash
bookstack search "rust"
bookstack search "rust" --type page --count 10
```

### Get Page with Full Content

```bash
bookstack get-page 308 --content      # show HTML content
bookstack get-page 308 --markdown     # show markdown content
```

## Next Steps

- See the [CLI Reference](cli-reference) for all commands and options.
- Check out [Generic Package Publishing Debugging](generic-package-publishing-debugging) for CI/CD integration notes.