yggy CLI

The yggy CLI calls the REST API with an API key, from your terminal or a script. It is a single program named yggy. To call the API from your own code instead, see the SDKs.

Install

On macOS and Linux, run the install script:

curl -fsSL https://github.com/yggy-tech/yggy-cli/releases/latest/download/install.sh | sh

The script downloads the latest release for your system (amd64 or arm64), checks it against the SHA-256 checksum published with the release and puts yggy in ~/.local/bin. It tells you if that folder is not on your PATH. Read it first at install.sh if you like.

YGGY_VERSION=0.1.0 installs a specific release instead of the latest.
YGGY_INSTALL_DIR=/usr/local/bin installs somewhere else. You need write permission there.

Check the result with yggy version.

On Windows, download the zip for your system from the releases page and put yggy.exe on your PATH. An installer for Windows is coming soon. Homebrew and other package managers are coming soon too.

The CLI is open source: github.com/yggy-tech/yggy-cli. To build it yourself you need Go 1.25 or newer:

git clone https://github.com/yggy-tech/yggy-cli
cd yggy-cli
go build -o yggy .

Update

yggy update

yggy update finds the latest release, checks its SHA-256 checksum and replaces the running yggy with it. yggy update --check only says whether a newer release exists. yggy update --version 0.1.0 installs a specific release, which also works to go back to an earlier one. The CLI never checks for updates on its own.

If yggy lives in a folder you cannot write to, the command says so. Run it with permission to write there, or install again with the script. A build from source does not update itself, because it has no release version: build it again, or install a release over it with --version.

Log in

yggy auth login

In a terminal the CLI asks for the API base URL (press Enter for https://api.yggy.tech) and how you want to log in.

In your browser is the default. The CLI prints a one-time code, opens https://app.yggy.tech/device and waits. Sign in to yggy if you are not, check that the page shows the same code, and approve. The CLI then stores an API key that yggy created for you, named yggy CLI with the date. It can read and upload documents and ask questions, never more than your own role allows, and it expires after 90 days; run yggy auth login again then. Find it under Developers → API keys and revoke it there at any time. The CLI prints logged in as with your account when it is done, so you can check it is the right one. Only approve a code you started yourself. If the browser does not open, for example over SSH, the CLI prints the address; --no-browser does that on purpose. Use yggy auth login --web to skip the question.

With an API key is for scripts and CI. Pass --base-url and --api-key, or set YGGY_BASE_URL and YGGY_API_KEY. A flag wins over the variable. Prefer the variable: a flag value can show up in your shell history and in the process list. On a terminal without those, the CLI asks for the key and hides it while you type. Without a terminal the CLI never opens a browser; use a key.

Login checks the key by listing the organizations it can see. An organization key sees only its own organization. With one organization, the CLI selects it. With several, run yggy use org next. The CLI saves the URL, the key and your selection in plain text in yggy/config.json in your user configuration folder, for example ~/.config/yggy/config.json on Linux or ~/Library/Application Support/yggy/config.json on macOS. Only your user can read the file. In CI, set YGGY_API_KEY from the CI secret store, log in during the job, and delete the config file when the job ends, or use a runner that is discarded after each job.

Any personal or organization key works. See Authentication.

Pick an organization and a project

yggy use org [name] selects an organization the key can see, by slug, name or id. Without a name it lists them and asks for a number; in a script, pass the name.
yggy use project [name] selects a project in that organization the same way. Selecting another organization clears the project.
yggy context shows the API URL, the kind of key (ygg_… or ygg_org_…, never the key itself), the organization and the project.
yggy orgs lists the organizations the key can see and yggy projects lists the projects of the selected organization. A * marks the current selection.

Commands

yggy auth login [--base-url URL] [--api-key KEY | --web] [--no-browser]
yggy use org [name]
yggy use project [name]
yggy context

yggy orgs
yggy projects
yggy documents list
yggy documents upload <file>
yggy documents wait <id>
yggy documents triples <id>

yggy ask <question>
yggy chat
yggy query <question>

yggy api
yggy api <operation> [args]

yggy update [--check] [--version X.Y.Z]
yggy version

yggy help prints this list. yggy <command> --help prints the options of one command, and a command used the wrong way prints only its own usage.

yggy documents list prints the newest documents of the selected project with their id, status and number of facts. --status filters by status (pending, processing, completed, failed or stored) and --limit shows up to 500 (20 by default).
yggy documents upload <file> uploads a file into the selected project and prints the document id.
yggy documents wait <id> checks the document every 2 seconds until processing finishes, then prints the id. It fails when processing fails, and after 15 minutes with still processing.
yggy documents triples <id> prints the document’s extracted facts as JSON.
yggy ask <question> asks the yggy agent. It reads your knowledge graph and documents, writes an answer and lists the documents it used under Sources. --tier fast, balanced (the default) or accurate trades speed for depth.
yggy chat starts a conversation with the yggy agent. Type a question and press Enter; each answer knows the earlier questions and answers, so you can ask follow-ups such as “and who signed it?”. /new starts a new conversation, and /exit or Ctrl-D ends it. Each question carries the last 10 questions and answers. --tier works as for ask. Without a terminal, chat reads one question per line from its input.
yggy query <question> finds the documents that match a question without writing an answer. It prints the best matching passage and then the ranked documents with their score, id and a snippet. --top-k N returns up to 20 documents (5 by default). --mode lexical matches document text only and --mode graph matches graph facts only; the default hybrid uses both. --include entities,triples adds the matching entities and facts.
ask, chat and query search the selected project, or the whole organization when no project is selected. You can put the question in quotes or not, and the options before or after it. Add --json to ask, query or documents list to print the API response instead. In a terminal, ask and chat show bold text and headings from the answer as bold; set NO_COLOR to turn that off.
yggy update and yggy version are described under Update.

The document commands need a selected organization and project. ask, chat, query and projects need a selected organization.

For example:

id="$(yggy documents upload Q4-report.pdf)"
yggy documents wait "$id"
yggy documents triples "$id" > q4-facts.json
yggy ask "Which contracts renew in Q1?"
yggy query "contract renewal Q1" --top-k 10

Call any operation

yggy api lists the operations of the public API with their method, path and summary. yggy api <operation> [args] calls one in the selected organization:

yggy api getDocumentStatus id=<id>

Path and query parameters are name=value. projectId defaults to the selected project.
Other name=value pairs become JSON body fields. Use name:=json for numbers, booleans, arrays and objects.
For uploads, field=@path attaches a file.
--data JSON or --data @file sends a whole body, and -o file writes the response to a file.

The CLI prints JSON responses indented. These are the operations the public SDKs support. The Reference describes their parameters.

Exit codes

Code	Meaning
`0`	Success
`1`	The call failed, for example a network error, an error from the API, a failed document or no login yet
`2`	Wrong usage or a missing choice, for example an unknown command, a wrong argument or no organization or project selected