Metadata-Version: 2.4
Name: agentself
Version: 0.1.0a3
Summary: Local identity for an agent: wallet, secrets, and optional email
Author: AgentSelf
License-Expression: MIT
Project-URL: Homepage, https://github.com/agentself/agentself
Project-URL: Repository, https://github.com/agentself/agentself
Project-URL: Issues, https://github.com/agentself/agentself/issues
Keywords: agent,identity,wallet,secrets,email,cli,local
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: eth-account<0.14,>=0.13.7
Dynamic: license-file

# agentself

`agentself` gives an agent a persistent local identity: a wallet, encrypted
secrets, and optional email. It is a CLI first, with one command tree across
the supported backends.

Linux, macOS, and Windows. Python 3.11+. This is the first public alpha, so
review [COMPATIBILITY.md](COMPATIBILITY.md) before automating against it.

## Install

```bash
uv tool install agentself
```

Or:

```bash
pipx install agentself
```

## Quick start

```bash
agentself install --tools
agentself init
agentself wallet address
agentself secret create API_TOKEN --file ./api-token.txt
agentself email connect
```

`init` creates one identity directory. Run `agentself show` to inspect it;
repeat `init` is safe, and `--force` is required to change an existing
identity or its backends. Email setup is optional and does not block init.

## Commands

| Area | Commands |
| --- | --- |
| Identity | `init`, `show`, `diagnose` |
| Secrets | `secret create`, `get`, `update`, `list`, `delete`, `exists` |
| Wallet | `wallet show`, `address`, `balance`, `authorize`, `verify`, `send` |
| Email | `email connect`, `show`, `send`, `receive`, `list` |
| Backends | `backends [CHANNEL]` |
| Recovery | `backup`, `restore` |
| Setup | `install --tools`, `install --skills` |

Use the CLI for the exact current flags and input rules:

```bash
agentself --help
agentself wallet --help
agentself email --help
```

## Backends & configuration

Backends keep the public commands stable while allowing the implementation to
change:

```bash
agentself backends
agentself backends wallet
agentself backends email
agentself backends store
```

| Capability | Default | Alternatives |
| --- | --- | --- |
| Wallet | `base` | `ethereum` |
| Email | `agentmail` | `imap` |
| Secrets | `sops` | `pass` |

Choose a backend during initialization:

```bash
agentself init --wallet ethereum --email imap --store pass
```

Wallet and email backends can also be selected with
`AGENTSELF_WALLET_BACKEND` and `AGENTSELF_EMAIL_BACKEND`. The precedence is
CLI flag, environment variable, saved identity configuration, then default;
there is no automatic failover. Backend-specific setup, credential sources,
and required host settings are exposed by `agentself backends` and
`agentself email connect`.

The identity directory is `~/.agentself` by default. Set
`AGENTSELF_IDENTITY_DIR` to isolate identities, for example:

```bash
AGENTSELF_IDENTITY_DIR=~/.agent-a agentself init
AGENTSELF_IDENTITY_DIR=~/.agent-b agentself init
```

Use `AGENTSELF_EMAIL_ADDRESS` and `AGENTSELF_EMAIL_CREDENTIAL` for transient
email configuration when appropriate. Runtime environment credentials are
not copied into the identity; complete `email connect` with its secure result
file when the credential should be encrypted into the identity.

## Automation and agents

The CLI is designed to be discovered from a shell. No MCP server or Python
import is required:

```bash
agentself --help
agentself backends
agentself diagnose
```

For automation, prefer `--json`. Successful and failed commands emit one JSON
object; human-readable errors stay on stderr. Exit codes are `0` for success,
`1` for an error, `2` for a refusal, and `3` when an input, dependency, or
resource is missing. `agentself --json --version` reports the package version
and machine-output schema version. Consumers should ignore unknown JSON keys.

An optional bundled skill provides the same discovery guidance to compatible
coding agents:

```bash
agentself install --skills
agentself install --skills -g
```

## Security

- Secret values are encrypted at rest by the configured store.
- Secret listings return names, not values; `wallet.key` requires `--unsafe` to export.
- Logs and structured errors redact secret values.
- Missing credentials and host tools fail instead of silently switching backends.
- Wallet backends are live; `wallet send` can move real assets.
- Identity files are replaced atomically, and wallet-send retries do not create a second payment.

Back up an identity with `agentself backup PATH`. Report vulnerabilities
through [SECURITY.md](SECURITY.md).

## Extending agentself

New backends implement the existing channel contract and do not add
provider-specific CLI verbs. See [CONTRIBUTING.md](CONTRIBUTING.md).

## Development

```bash
git clone https://github.com/agentself/agentself
cd agentself
uv sync
uv run pytest
uv run ruff check .
uv run mypy agentself
```

See [RELEASE.md](RELEASE.md) for the small-project release checklist.

## License

[MIT](LICENSE)
