Marona CLI
Author: Blessing Nyuwani.
The Python command line client for Marona Agents, Hub capabilities, protocol
sessions and MCP development. 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:
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.0.1. Installation also installs the required
Python SDK 2.12.2 or later. No repository checkout is needed.
For an isolated command available anywhere, use one of:
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:
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
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:
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,
)
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:
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
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
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.
Metadata
Release files for marona-cli 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| marona_cli-1.0.1.tar.gz | 28.3 kB | Without provenance | Details for marona_cli-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| marona_cli-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for marona_cli-1.0.1-py3-none-any.whl |
Total release size: 50.6 kB
Release files / marona_cli-1.0.1.tar.gz
| Download URL | marona_cli-1.0.1.tar.gz |
|---|---|
| Size | 28.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e826f426aa48289f75afa3f4b9f6c13e940678c9f715ca5dd81c9ee03b648e2f
|
|
BLAKE2b-256 checksum How to use checksums |
266fc6a7cf264f3dc81697b58ebd88c1a23aff0d01d66c94bfaf26071fc6e6b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.6 {"installer":{"name":"uv","version":"0.11.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / marona_cli-1.0.1-py3-none-any.whl
| Download URL | marona_cli-1.0.1-py3-none-any.whl |
|---|---|
| Size | 22.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
10651b4e220347672cf3d5c65609b8d1662ec2b84e7e3402daae9033842dc630
|
|
BLAKE2b-256 checksum How to use checksums |
2cc1341e621e8e97c2bd5c2d520d75bc3989f2b6331f05cf8de1826d64d6c311
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.6 {"installer":{"name":"uv","version":"0.11.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for marona-cli 1.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.