Metadata-Version: 2.4
Name: aia-cli
Version: 0.1.10
Summary: Keep a folder on your computer in sync with your AIA knowledge graph
Author: 013a
License-Expression: LicenseRef-Proprietary AND Apache-2.0
Project-URL: Homepage, https://013a.tech
Keywords: aia,knowledge-graph,sync,connector
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSES/Apache-2.0.txt
Requires-Dist: cryptography>=42.0.0
Provides-Extra: watch
Requires-Dist: watchdog>=6.0.0; extra == "watch"
Provides-Extra: channel
Requires-Dist: websockets>=12.0; extra == "channel"
Dynamic: license-file

# aia-cli

Keep folders on your device in sync with AIA, your own knowledge graph.

## Install

On a Mac (Apple silicon or Intel), or Linux on x86_64, one line installs `aia` for your
user, with no password and no Python needed. It fetches AIA's engine for this
computer from your deployment (here the hosted one; your own serves the same script
at its own address):

```bash
curl -fsSL https://app.013a.tech/install.sh | sh
aia folder add notes ~/Documents/notes
```

The script checks the engine's SHA-256 before it installs it under
`~/Library/Application Support/AIA` (Linux: `~/.local/share/aia`), links `aia` into
`~/.local/bin`, signs this computer in (`aia login` opens your browser at the
sign-in page with the code filled in, and waits until you have signed in) and starts
AIA in the background. `sh -s -- --no-login` after the pipe stops after the install;
`sh -s -- --help` lists the rest, exit codes included.

Anywhere with Python 3.10 or newer, install the package from PyPI with
[pipx](https://pipx.pypa.io) instead:

```bash
pipx install "aia-cli[watch,channel]"
aia login --url https://api.013a.tech
aia folder add notes ~/Documents/notes
aia service install          # keep AIA running in the background
```

The package is `aia-cli`; the command it installs is `aia`. A package called
`aia` on PyPI belongs to an unrelated project: `pip install aia` installs someone
else's code. That project also installs a Python module named `aia`, so the two
cannot share an environment: whichever loads second breaks the other. pipx gives
`aia` an environment of its own. Without pipx, install with `pip` into a virtual
environment that holds nothing else.

The same `install.sh`, run as a file beside a wheel, installs that wheel, and
`--wheel FILE` names one; a Mac ships Python 3.9, so there it downloads a pinned
CPython from python-build-standalone and checks its SHA-256 first.

## Where a release comes from

Every version on PyPI is built by CI from the tag `cli-v<version>`, which must
name the version the package declares. The release keeps `SHA256SUMS` for the wheel
and the sdist, a SLSA provenance statement naming the commit and the pipeline that
built them, and a minisign signature over both, checked against the release key below
before anything is uploaded. After the upload it compares the SHA-256 PyPI serves
for each file with `SHA256SUMS`, and any difference fails the release. To check a
release yourself, ask support@013a.tech for its files, then:

```bash
minisign -Vm SHA256SUMS -P <the release key>
minisign -Vm aia_cli-<version>.provenance.json -P <the release key>
sha256sum -c SHA256SUMS
```

The release key:

```
RWTTmOTyJEm+M0inq5FoBCOsMY3vil/aMLfn0C6KbOIR4zqATOAecVmN
```

Releases up to 0.1.9 were signed with the previous key, retired on 2026-10-19: `RWSVfBZY/SJjE2WsgLMqe1PCawH+/PVD29Ic396wRIrOCGxf6WGsrNwZ`.

## What it does

`aia` binds a folder to a source and sends what changes. The documents travel as
**bytes**: the platform extracts the text, so a PDF reads the same however the
folder was synced, and upgrading the converters does not mean re-sending a corpus.

An engine runs in the background, watches the folders you bound, coalesces a burst
of edits into one sync, and reconciles on an interval because file events are lossy.
`aia` itself is a renderer over the engine's methods, and runs them in-process when
no engine is running.

## What it will not do

* **It never sends your AIA credentials.** The configuration home holds this
  device's token and its private key, and a folder that is it, contains it, or sits
  inside it is refused by name.
* **It stops a whole sync when it finds a secret.** A file whose name says what it
  is (`.env`, `id_rsa`, `*.pem`) or whose contents match a credential pattern holds
  the sync until you allow that exact path. A partial sync that quietly skipped
  something is how a corpus ends up wrong in a way nobody sees.
* **It listens on nothing.** The engine serves its methods over a Unix socket in an
  owner-only directory and checks the peer's user id before reading a byte. There is
  no network listener; everything towards your deployment is outbound.
* **It never writes to your files.** Removing a folder stops syncing it; nothing
  here creates, moves or deletes anything on your disk.

## What is installed

`cryptography`, for the Ed25519 signature on every request. Nothing else is
required. Two extras are available and neither is needed to sync:

```bash
pip install "aia-cli[watch]"     # platform file events instead of polling
pip install "aia-cli[channel]"   # reachable from your tools, over an outbound socket
```

The distribution deliberately carries none of the server's dependencies. If
`pip install aia-cli` ever brings in liboqs, Neo4j, torch, FastAPI or a
document converter, that is a bug and the import-closure gate in CI should have
caught it.

## Exit codes

| code | meaning |
|---|---|
| 0 | it did what it was asked |
| 1 | an error this table does not name |
| 2 | bad arguments |
| 3 | the record of what left this device and AIA disagree (`aia folder verify`, `aia egress verify`) |
| 4 | not signed in |
| 5 | the deployment answered, and the answer was no |
| 6 | the deployment or the engine could not be reached |
| 7 | another engine already holds this device's lock |
| 8 | a sync was refused because the folder holds something that looks like a secret |
| 130 | stopped with Ctrl-C |

Every failure prints `error:` and the one thing to do next. A problem the command did
not expect writes its details to `~/.config/aia/cli.log` and says so; `--debug` shows
them in the terminal instead. `aia --version` names the build, which is what a bug
report needs.

## Licence

Proprietary: © 013a GmbH, all rights reserved. You may use the connector only under a
written agreement with 013a GmbH; for testers, that is the tester agreement. One file it
ships, `aia/__init__.py`, is shared with the open-source verifier and is Apache-2.0. The
wheel carries `LICENSE` and `LICENSES/Apache-2.0.txt`.
