Metadata-Version: 2.4
Name: glossa-cli
Version: 0.1.0
Summary: Command-line client and MCP server for Glossa — analyze text and manage your vocabulary from the terminal or any MCP-aware LLM client
Project-URL: Homepage, https://glossa.pro
Project-URL: Repository, https://github.com/artemiy-rodionov/glossa
Project-URL: Issues, https://github.com/artemiy-rodionov/glossa/issues
Author-email: Artemiy Rodionov <artemiy.rodionov@gmail.com>
Keywords: cli,flashcards,fsrs,glossa,language-learning,vocabulary
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28
Requires-Dist: mcp>=1.2
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# glossa-cli

A standalone command-line client for [Glossa](https://glossa.pro) — analyze text
and manage your vocabulary from the terminal.

You'll need a Glossa account — sign up at
[glossa.pro](https://glossa.pro). For setup help and the full integration
guide, see [glossa.pro/account](https://glossa.pro/account).

## Install (one command)

```sh
pipx install glossa-cli      # recommended — isolated install
# or:
pip install glossa-cli
```

Both put **two** binaries on your PATH:

- `glossa` — the terminal CLI for vocabulary management
- `glossa-mcp` — a stdio MCP server for Claude Desktop, ChatGPT, etc.

## Sign in

Run `glossa login` first. It opens a browser to authorise you; after you
approve, your tokens are cached in `~/.config/glossa/credentials.json` and
refreshed automatically — you won't need to sign in again.

```sh
glossa login          # opens a browser; prints an auth URL to approve
glossa login --force  # clear the cached sign-in and authorise again
glossa logout         # sign out — remove cached credentials
```

Switching accounts is `glossa logout && glossa login` (or just
`glossa login --force`). The `glossa-mcp` server reads the same credentials
file, so re-auth on the CLI then restart your MCP client to pick up the
new sign-in.

> **CI / scripting:** skip the browser flow by exporting a static token from
> Glossa → Settings → Tokens: `export GLOSSA_API_TOKEN=glossa_xxx`.

## Quick start

```sh
glossa login                                          # one-time browser sign-in
glossa add serenity                                   # add a word to your vocabulary
glossa list --status learning                         # see what you're learning
glossa review                                         # interactive FSRS review
echo "We've done the impossible, and that makes us mighty." | glossa analyze    # CEFR breakdown
```

If your account has multiple learning languages enabled, Glossa will ask you
to pick one. Set a default with `glossa lang set <code>` (persistent), or
`export GLOSSA_LANG=<code>` (session). Single-language accounts don't need to
think about this.

## MCP server

The same install ships `glossa-mcp`, a stdio MCP server for Claude Desktop,
ChatGPT, and other MCP-aware LLM clients. Add it to your client's config —
full setup guide is in the Glossa Account → MCP tab. To smoke-test:

```sh
glossa-mcp
# Run interactively → prints a brief help message explaining how to use it.
# Run with piped JSON-RPC on stdin → serves the protocol on stdout.
```

## Usage

```sh
# Analyze text (arg, --file, or stdin) — language auto-detected
echo "And we choked 'em with those words." | glossa analyze
glossa analyze --file article.txt
glossa analyze "a short sentence" --json

# Add a word or phrase
glossa add serenity --status learning
glossa add "hold my beer" -t "watch how it's done"

# Change a word's state (upserts by lemma; --id targets one sense)
glossa set serenity known
glossa set --id 1234 saved

# List your vocabulary
glossa list --status learning
glossa list --json

# Interactive FSRS review session
glossa review

# Default learning language (only needed if your account has 2+ enabled)
glossa lang                # show current default + source
glossa lang set fr         # persist to ~/.config/glossa/config.json
glossa lang unset
```
