Skip to main content

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:

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:

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.

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.

Metadata

Release files for marona-cli 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for marona-cli 1.1.0
File Size Uploaded Provenance Actions
marona_cli-1.1.0.tar.gz 36.8 kB Without provenance Details for marona_cli-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for marona-cli 1.1.0
File Interpreter ABI Platform Actions
marona_cli-1.1.0-py3-none-any.whl Python 3 none any Details for marona_cli-1.1.0-py3-none-any.whl

Total release size: 72.5 kB

Release files / marona_cli-1.1.0.tar.gz

Download URL marona_cli-1.1.0.tar.gz
Size 36.8 kB
Tags Source
SHA-256 checksum
How to use checksums
80b46ff80985c36b21f38ce576e01190c042dbcfc988e4c1be48498a865316d4
BLAKE2b-256 checksum
How to use checksums
540c7d6bc955f4855b2131f99591a4ecfae020e72122b597bc915a7c6d92ea6a
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.1.0-py3-none-any.whl

Download URL marona_cli-1.1.0-py3-none-any.whl
Size 35.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d90e4c9f096e4f3d7f2966e5343ea3b9373ad3f620049c207a0eb97887e92466
BLAKE2b-256 checksum
How to use checksums
22744c61953dc87ff2865afd5a7840fef7bb48347c245020205b0fd4057ac719
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.1.0

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.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page