Documentation Index
Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
Use this file to discover all available pages before exploring further.
These commands handle initial developer setup and ongoing authentication. Most developers run murmur setup once per repo and never think about authentication again.
murmur setup
The primary onboarding command. Gathers your credentials (GitHub token, Claude token, SSH signing key), encrypts them, and writes the encrypted profile to .murmur/murmur.local.yaml.
Flags
| Flag | Type | Description |
|---|
--out | string | Output path for the encrypted local config (default: .murmur/murmur.local.yaml) |
--non-interactive | bool | CI-friendly mode. Reads credentials from environment variables instead of prompts. |
--skip-ssh-keys | bool | Skip SSH signing key generation (useful in CI where commit signing is not needed) |
--commit-signing | bool | Upload the SSH signing key to GitHub for verified commit badges |
--upload | bool | Upload the encrypted profile to the platform (for VMs to use) |
Interactive flow
The interactive setup walks through these steps:
- GitHub identity: Discovers your GitHub login and token via
gh auth token
- Tenant selection: Lists your available tenants (personal account and orgs with the Macroscope GitHub App installed) and prompts you to choose
- Claude credentials: Opens a browser for Claude OAuth authorization, or prompts for an API key
- OpenAI key (optional): Discovers
OPENAI_API_KEY from your environment for Codex backend support
- SSH signing key: Generates an ed25519 SSH key pair for signing commits on VMs
- Workspace config: Creates
.murmur/murmur.yaml (shared team config) if it does not already exist
- Encrypted profile: Encrypts all credentials and writes
.murmur/murmur.local.yaml (gitignored)
Non-interactive mode (CI/automation)
For CI pipelines and automation, set credentials via environment variables and run in non-interactive mode:
export GH_TOKEN="ghp_..."
export ANTHROPIC_API_KEY="sk-ant-..."
murmur setup --non-interactive --skip-ssh-keys
| Environment variable | Purpose |
|---|
GH_TOKEN | GitHub personal access token |
ANTHROPIC_API_KEY | Anthropic API key (alternative to OAuth) |
OPENAI_API_KEY | OpenAI API key for Codex backend (optional) |
Commit signing
Upload your SSH signing key to GitHub so commits made by agents show as “Verified”:
murmur setup --commit-signing
Named contexts
Create separate credentials for different environments using --out and MURMUR_CONTEXT:
# Set up staging credentials
MURMUR_CONTEXT=staging murmur setup --out .murmur/murmur.staging.local.yaml
# Set up production credentials
MURMUR_CONTEXT=production murmur setup --out .murmur/murmur.production.local.yaml
What gets written
| File | Content | VCS |
|---|
.murmur/murmur.yaml | Workspace name, tenant, model defaults, API address | Committed (shared) |
.murmur/murmur.local.yaml | KMS-encrypted developer profile (tokens, keys) | Gitignored |
.murmur/.gitignore | Patterns for *.local.yaml and other sensitive files | Committed |
murmur install
Interactive guided setup for .murmur/murmur.yaml. This creates the shared workspace configuration that the entire team uses.
The install wizard prompts for:
- Workspace name: A short identifier for your team/project
- Repositories: Which repos agents should clone
- Default model: Claude model for agent sessions
- API endpoint: Platform API address (defaults to the hosted service)
murmur install
# ? Workspace name: backend-team
# ? Repository URL: https://github.com/acme/api
# ? Add another repository? (y/N): n
# ? Default model: claude-sonnet-4-6
# Created .murmur/murmur.yaml
murmur install only creates the shared config. Run murmur setup afterward to create your personal encrypted profile.
murmur install-repo
Install the GitHub webhook and Actions workflow for real-time event delivery to agents. This enables agents to receive PR comments, CI results, and other GitHub events.
murmur install-repo --webhook-url <url>
Flags
| Flag | Type | Description |
|---|
--webhook-url | string | The webhook endpoint URL for event delivery (required) |
murmur install-repo --webhook-url https://api.murmur.ai/webhooks/github
- Installs a GitHub webhook on the repository pointing to the provided URL
- Configures the webhook to deliver events: push, pull_request, issue_comment, check_run, check_suite
- Optionally sets up a GitHub Actions workflow for CI event forwarding
The webhook URL is typically the Murmur API’s GitHub webhook endpoint. It enables real-time event delivery so agents can react to PR comments, CI failures, and code reviews.
murmur auth
Authenticate with the Murmur API. Opens a browser for GitHub OAuth authorization and outputs export lines with the resulting token.
What happens
- Opens your browser to GitHub’s OAuth authorization page
- After authorization, receives a Murmur identity token
- Prints export lines to set the token in your shell
murmur auth
# Opening browser for GitHub OAuth authorization...
# Authorization successful.
#
# Export these in your shell:
# export MURMUR_TOKEN="eyJhbGciOiJSUzI1NiIs..."
eval $(murmur auth 2>/dev/null)
When to use
- First time: Part of initial setup (usually handled by
murmur setup)
- Token expired: Re-authenticate when your token expires
- CI pipelines: Generate a token for automation scripts
- Troubleshooting: Verify authentication works independently of
murmur setup
murmur connect
Test connectivity to the Murmur API. Verifies that the CLI can reach the API endpoint and that your credentials are valid.
Example output
API: https://api.murmur.ai
Status: connected
Tenant: acme-corp
User: alice
Latency: 45ms
API: https://api.murmur.ai
Status: failed
Error: authentication failed: token expired
Hint: Run 'murmur auth' to refresh your token
Troubleshooting checklist
| Symptom | Likely cause | Fix |
|---|
connection refused | API endpoint unreachable | Check network, VPN, or api.address in config |
authentication failed | Token expired or missing | Run murmur auth or murmur setup |
tenant not found | Workspace points to wrong tenant | Check workspace in .murmur/murmur.yaml |
permission denied | GitHub App not installed for org | Install the Macroscope GitHub App on your org |
murmur version
Print version information.
Flags
| Flag | Type | Description |
|---|
--client | bool | Print only the client version (no API call) |
# Client version only (offline)
murmur version --client
# murmur v0.42.0 (abc1234) built 2025-01-15
# Client and server versions
murmur version
# Client: v0.42.0 (abc1234) built 2025-01-15
# Server: v0.42.0
--client for a quick offline check (no API connectivity required). Without the flag, the CLI also queries the API for the server version.
