Metadata-Version: 2.4
Name: tuluai-malple-cli
Version: 0.1.0
Summary: Use Malple from a terminal with a permission-scoped local workspace.
Author: TuluAI
License-Expression: MIT
Project-URL: Homepage, https://tuluai.app/malple
Project-URL: Documentation, https://tuluai.app/docs/malple-cli
Keywords: malple,tuluai,terminal,automation
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Malple CLI

Use Malple from a terminal with the `malple-cli` command. The pilot package is
published on PyPI as `tuluai-malple-cli`.

## Install

Python 3.10 or newer is required. The package uses the Python standard library.

```bash
python -m pip install tuluai-malple-cli
malple-cli --help
```

## Sign in and enable a folder

```bash
malple-cli login
malple-cli workspace add ~/projects/my-project
malple-cli ask --workspace ~/projects/my-project "Summarize the changed files"
```

Sign in with the account used for Malple. The password is entered without being
shown and is not saved. The short-lived session token is stored in the local
user configuration directory with private file permissions on macOS and Linux.
On Windows, it is stored under the current user's application-data folder and
protected by that account's file permissions.
`malple-cli logout` removes the saved session.

Adding a folder is an explicit local permission grant. Malple can only list,
read, and write text files inside folders you enabled. File content read to
complete a request may be sent to TuluAI. Symbolic links are not followed,
`.git` internals are hidden, and individual file reads and writes are limited to
64 KB.

## Local tasks supported in this pilot

- List files and folders inside an enabled workspace.
- Read UTF-8 text files up to 64 KB.
- Create or replace UTF-8 text files up to 64 KB.
- Run fixed, read-only checks: show the workspace path, show the Python version,
  show Git status, or summarize the Git diff.

Malple does not run arbitrary shell commands, install software, control the
mouse or keyboard, or access folders you have not enabled. Press `Ctrl+C` to
stop the current terminal run. Completed local actions are recorded without
storing prompts or file contents.

## Commands

```text
malple-cli login
malple-cli status
malple-cli workspace add PATH
malple-cli workspace list
malple-cli workspace remove PATH
malple-cli ask [--workspace PATH] "Describe the task"
malple-cli history
malple-cli history --clear
malple-cli logout
```

If one folder is enabled, it is selected by default. If multiple folders are
enabled, pass `--workspace` to choose one. Tasks can also be sent without a
workspace, but local file and terminal tools will not be available.

## Service address

The default service address is `https://tuluai.app`. To use a compatible
development service, set `MALPLE_BASE_URL` before running the CLI. The CLI
retrieves the public sign-in configuration from the service and does not require
users to paste an API key into a command.

## Troubleshooting

- **Email verification required:** verify the account in the browser, then run
  `malple-cli login` again.
- **Session expired:** run `malple-cli login`; passwords are never saved.
- **Folder is not enabled:** run `malple-cli workspace add PATH` and grant access.
- **Task stopped:** rerun it or check `malple-cli history` for completed actions.
- **Service unavailable:** check the service address and internet connection.

## Development tests

```bash
PYTHONPATH=packages/malple-cli/src python -m unittest discover -s packages/malple-cli/tests -v
```
