Metadata-Version: 2.4
Name: marona-cli
Version: 1.1.0
Summary: Marona CLI for Python, Rust, Java, TypeScript and Dart SDK projects, Agents and MCP development.
Author: Blessing Nyuwani
License-Expression: MIT
Project-URL: Homepage, https://www.marona.ai
Project-URL: Documentation, https://platform.marona.ai/docs
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: marona<3,>=2.13.0
Requires-Dist: keyring<26,>=25
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: ruff<1,>=0.14; extra == "dev"
Dynamic: license-file

# Marona CLI

Author: **Blessing Nyuwani**.

The shared command line client for Marona Agents, Hub capabilities, protocol
sessions and MCP development across Python, Rust, Java, TypeScript and Dart. It uses the official `marona` SDK for execution.
Source lives in this repository at `clients/cli`; it is not a separate service.

## Install

Python 3.10 or later. Install in a virtual environment:

```sh
python3 -m venv .venv-cli
. .venv-cli/bin/activate
python -m pip install --upgrade marona-cli
marona --help
marona version
```

The CLI package is `marona-cli` 1.1.0. Installation also installs the required
Python SDK 2.13.0 or later. No repository checkout is needed.

For an isolated command available anywhere, use one of:

```sh
pipx install --include-deps marona-cli
# Or:
uv tool install --with-executables-from marona marona-cli
```

On Windows, activate the virtual environment with `.venv-cli\\Scripts\\Activate.ps1`
instead of the shell activation command above. Each developer authenticates with
their own Marona key using `marona auth login` or `MARONA_API_KEY`.

The SDK owns the existing `marona` launcher and delegates to this package when
installed. This avoids two packages overwriting the same executable. SDK-only
installations retain their existing `version`, `build`, `publish` and `deploy`
commands. `marona-cli` and `python -m marona_cli` also invoke the full CLI.

## Credentials and settings

Set `MARONA_API_KEY` in your shell/CI secret environment, or run:

```sh
marona auth login
marona auth status --verify
marona config set --model marona/auto --user-id developer-123
marona config show
marona doctor
```

Login reads a hidden prompt, verifies access with a read-only runtime request,
and stores the key in macOS Keychain, Windows Credential Locker, Secret Service
or KWallet. It never falls back to a plaintext credential file. Headless hosts
can use environment variables; a secret manager may pipe to `auth login
--key-stdin` when an OS store is available. `auth logout` removes the stored
credential for the current profile/endpoints; it cannot unset your parent
shell's environment variable. Platform operations also accept
`MARONA_DEVELOPER_TOKEN` for an authenticated developer session.

Profiles hold only runtime URL, platform URL, model and user identity. Defaults
are `https://edge.marona.ai`, `https://platform.marona.ai/api`, and `marona/auto`.
Settings resolve in this order: command flags, environment, profile, defaults.
Use `--profile staging` or `MARONA_PROFILE` to select a profile. Supported
environment settings are `MARONA_RUNTIME_URL`, `MARONA_PLATFORM_URL`,
`MARONA_MODEL`, and `MARONA_USER_ID`. The settings file is
`$XDG_CONFIG_HOME/marona/config.json` (normally `~/.config/marona/config.json`),
or `%APPDATA%/marona/config.json` on Windows. Override with `MARONA_CONFIG_FILE`.
Stored keys are bound to both endpoints and the profile, so changing an
endpoint does not send a previously saved credential to a different server.

## Agents

```sh
marona run 'Explain the BCI workflow'
marona run --stream 'Explain the BCI workflow'
marona chat --session-id my-conversation
marona run --app documents 'Find the project guide'
marona apps --search documents --limit 20
marona tools --app documents
printf '%s' 'Explain this briefly' | marona run
```

`chat` streams by default. `/new` creates a fresh session; `/exit`, EOF and Ctrl+C
end it. New runs use unique session IDs, written to stderr. Pass `--session-id`
to continue a conversation. Apps attach through `client.hub.connect`; the CLI
does not bypass runtime permissions, approvals, service authentication or tool
policies. Without `--app`, an inline Agent has no Hub tools attached.

For structured output, tools, A2A, B2A, D2A or other protocols, keep an ordinary
SDK `Agent` in your own `agent.py`:

```python
from marona import Agent
from pydantic import BaseModel, ConfigDict


class Answer(BaseModel):
    model_config = ConfigDict(extra="forbid")
    text: str


agent = Agent(
    name="Project Assistant",
    model="marona/auto",
    instructions="Answer clearly and concisely.",
    output_type=Answer,
    output_schema_strict=True,
)
```

```sh
marona run --agent agent:agent --json 'Explain the workflow'
marona chat --agent agent:agent
marona run --agent agent:agent --input-json - < input.json
```

`--agent` imports and executes the named Python module. Use only trusted local
code. The SDK client exists before import, so the Agent binds to that client.
Instructions, model, tools, schemas and protocol definitions in the imported
Agent remain authoritative. `--input-json` passes standard SDK structured or
multimodal input; a prompt can also be supplied directly or piped as text.
Inputs are bounded to 4 MiB. Text/JSON output is UTF-8 and terminal controls are
removed from human output.

## Realtime protocols

Configure `Agent(protocols=[...])` normally in `agent.py`, including your B2A
provider or D2A device. The CLI uses the SDK's `Runner.connect` directly:

```sh
marona connect --agent agent:agent --user-id user-123 --session-id session-123
marona connect --agent agent:agent --protocol b2a --user-id user-123 \
  --input-json signal.json --signal
marona connect --agent agent:agent --protocol d2a --user-id user-123 \
  --input-json message.json
marona protocol validate b2a message.json
marona protocol validate d2a - < message.json
```

`connect` emits SDK events as newline-delimited JSON and stays open until Ctrl+C
or the SDK closes the session. It can send one optional initial message/signal
and receive provider streams. It does not impose the one-response timeout on a
persistent session. `run --agent ... --input-json ...` produces one complete
protocol result. Protocol validation runs locally without credentials or network
calls. The CLI does not invent message fields or neural/device behavior. Native
audio-device playback is not supplied by this terminal client; use the existing
media SDK adapters for speaker/microphone integration.

## MCP projects and hosting

```sh
marona init agent my-agent
marona init mcp greeting-tools
cd greeting-tools
marona mcp serve server:server
marona mcp serve server:server --transport stdio
marona publish --registration registration.json
marona deploy --app-id APP_ID --source-url https://github.com/OWNER/REPO \
  --branch main --secret-env MCP_API_KEY
marona deployments list --app-id APP_ID
marona deployments get --app-id APP_ID --deployment-id DEPLOYMENT_ID
```

Generated projects contain direct SDK objects, one requirements file, a
Dockerfile and short instructions. Existing directories are never overwritten.
Their only runtime dependency is the published `marona==2.12.1` SDK. Generated
Agents run with `python main.py 'Hello'` and MCP servers with `python server.py`.
Both Dockerfiles run Python directly; neither needs the CLI or an unpublished
package to build or run. The full CLI remains an optional development tool.
`mcp serve` defaults to loopback. Configure your service's allowed hosts,
origins and authentication when exposing HTTP. `publish` registers an App;
only `--submit` additionally submits it for review. `deploy` creates a hosted
deployment and may incur hosting charges. It defaults to branch `main`.
Private repository access must already be configured in Marona Platform; the
CLI does not upload your GitHub credentials or repository contents.

For an offline Python tool, implement the SDK's portable callable contract in
`marona_offline.py`, then build it with
`marona build --target python --source . --output dist/tools.zip`.
This packages only the entrypoint module by default. Use `--include` for each
additional module or asset; review explicit includes before distributing an
archive. `--target wasm` packages an existing WebAssembly binary. Building a
portable tool and deploying an HTTP MCP server are separate operations.

## Automation and errors

`--json` gives one JSON object for a completed run, or one event per line for
streaming. Informational messages and errors go to stderr. Commands perform no
automatic retries, so a network failure never silently repeats a tool/action.

Exit codes: `0` success, `1` execution failure, `2` invalid configuration/input,
`3` runtime/authentication/network error, `4` authorization or approval required,
`130` interrupted. `doctor` is local; use `auth status --verify` for a network
check. Credentials and response bodies are omitted from transport errors.

## Develop and release

```sh
python -m pip install -e './clients/python' -e './clients/cli[dev]'
python -m pytest clients/cli/tests
python -m ruff check --config clients/cli/pyproject.toml clients/cli
python -m build clients/cli
```

The CI matrix covers Python 3.10/3.13 on Linux, macOS and Windows and builds both packages.
Release the SDK dispatcher first, then the CLI. Publication workflows require
the current `main` revision. The CLI workflow must have a PyPI trusted publisher
configured for `marona-cli`. Both package workflows support a temporary isolated
runner with the same trusted identity when hosted runners are unavailable.

## Native SDK projects

`marona init agent my-agent --language typescript` creates a direct TypeScript
Agent project. `marona init mcp my-tools --language rust` creates a Rust MCP server.
Both commands support `python`, `typescript`, `rust`, `java` and `dart`, with native
build files and Dockerfiles. Use the generated README to build and run each project.

The npm, crates.io, Maven and pub.dev packages provide entry points for the same
Python CLI engine. Install `marona-cli` once with pipx, including dependencies.
They forward arguments, terminal streams and exit status without using a shell.
Set `MARONA_CLI_EXECUTABLE` to its executable path when it is outside PATH.
The engine is a development tool; native SDK applications have no Python dependency.

`--agent module:object` and `mcp serve` are Python object loaders. They do not
import Rust, Java, Dart or TypeScript source. Run native generated applications
with their native toolchain; registration and deployment commands work across all
languages.
