algorise 0.2.1

Unified CLI and MCP server for your Algorise workspace (read knowledge + publish agent output)

Algorise

Publish agent output into Algorise — from Claude Code, Cursor, CI, or any script.

Algorise is a CLI and MCP server that connects external coding agents to your Algorise workspace. Push files, notes, and links; choose where they land; collaborate with your team and digital employees; pull results back into your local workflow.

• Publish — files, URLs, or inline markdown land as reviewable artifacts
• Route — send work to your inbox, a Collection, Dataset, or Report
• Collaborate — post updates, request review, poll for replies from digital employees

Requires Python 3.12+ and an Algorise account.

Quick start

# Install (Python 3.12+; see INSTALL.md for all options)
uv tool install algorise

# Authorize via browser (OAuth — no API keys to paste)
algorise login

# Publish a file into your workspace inbox
algorise publish ./draft.md --title "Draft report" --agent claude-code

# See what you have published
algorise inbox

Published work appears in your Algorise dashboard, inbox, and notifications.

Install

This package installs two commands:

Command	Purpose
algorise	CLI for publishing and collaboration
algorise-mcp	MCP server (stdio) for in-editor agents

# Recommended — uv tool (persistent install, no system Python required)
uv tool install algorise

# Run without installing
uvx algorise login

# pip / pipx (needs Python 3.12+)
pipx install algorise

Full install notes: INSTALL.md.

Authenticate

Auth uses browser OAuth (OAuth 2.0 device-authorization grant). Tokens are short-lived, refreshable, centrally revocable, and act as you within your current organization.

algorise login

This prints a verification URL and user code, opens your browser, and waits for approval (you must already be signed in to Algorise). The session is saved to ~/.algorise/config (mode 600).

algorise whoami   # profile, URL, org/user/scopes
algorise logout   # clear the active profile's session

Active sessions can be listed and revoked in the product under Settings → Connected CLIs.

Typical workflow

# 1. Publish work from your repo or agent session
algorise publish ./analysis.md --title "Competitor scan" --agent cursor

# 2. Route directly into a knowledge base (optional)
algorise publish ./policy.pdf --to collection --collection <collection-id>

# 3. Request a human review from the CLI
algorise review <artifact-id> "Please verify the sources"

# 4. After a digital-employee handoff in the UI, poll for replies
algorise pull <agent-session-id>

Review, approve, and hand off to digital employees in the Algorise UI. Bridge delivers work into the workspace; it does not auto-publish on your behalf outside Algorise.

Profiles

One installed CLI can target multiple Algorise workspaces or accounts with per-profile saved tokens — similar to aws --profile.

algorise login --profile work      # sign in to one workspace
algorise login --profile personal  # sign in to another

algorise profiles                  # list profiles (* = active)
algorise use work                  # switch active profile
algorise --profile personal whoami # one-off override

algorise logout --profile personal # clear one profile
algorise logout --all              # clear everything

Profiles are stored in ~/.algorise/config. A legacy flat config is migrated automatically into a default profile on first use.

Resolution order

For each invocation, API URL and token resolve in this order (highest first):

1. --api-url URL (one-off; token from the selected profile or env)
2. --profile NAME
3. ALGORISE_BRIDGE_PROFILE env
4. ALGORISE_BRIDGE_API_URL / ALGORISE_API_URL (+ token env) — ad-hoc, no profile (CI)
5. Active profile in ~/.algorise/config
6. Local dev fallback (http://localhost:7100)

Environment variables

Most users only run algorise login. These exist for CI and headless runners:

Variable	Purpose
ALGORISE_BRIDGE_API_URL	API base URL (falls back through ALGORISE_API_URL, saved config, release default, then localhost)
ALGORISE_BRIDGE_DEFAULT_URL	Release-time public API base, baked into published builds
ALGORISE_BRIDGE_TOKEN	Session token override (falls back to ALGORISE_TOKEN, then saved config)
ALGORISE_BRIDGE_PROFILE	Named profile (same as --profile; used by the MCP server, which has no CLI flags)

When no URL is configured, commands that need the API fail with a clear message instead of silently hitting localhost.

CLI reference

Command	Description
algorise [--profile NAME] [--api-url URL] <command>	Global backend selectors
algorise login [--profile] [--api-url] [--name] [--scopes] [--no-browser]	Browser OAuth; saves token under profile
algorise logout [--profile] [--all]	Clear session(s)
algorise whoami	Show resolved profile, URL, org/user/scopes
algorise profiles (alias envs)	List configured profiles
algorise use NAME	Set the active profile
algorise publish PATH [--title] [--summary] [--type] [--agent] [--to …] [--collection ID] [--dataset ID]	Publish a file
algorise publish --url URL [--title]	Publish a URL as a link
algorise publish --text "…" [--title]	Publish inline markdown as a note
algorise note TEXT [--title] [--summary] [--agent]	Publish an inline note
algorise artifacts [--target] [--limit]	List published artifacts
algorise inbox [--limit]	List artifacts with compiled previews
algorise update ARTIFACT_ID BODY [--review]	Post a progress update
algorise notify TITLE MESSAGE [--url]	Send a standalone notification
algorise review ARTIFACT_ID [BODY]	Request review and show the thread
algorise pull SESSION [--since ISO]	Poll a collaboration session for replies
algorise quota	Show remaining ingest quota
algorise search QUERY [--types T1,T2] [--limit N]	Search the knowledge base, skills, agents, conversations (read)
algorise collections [COLLECTION_ID]	List accessible collections, or documents in one (read)
algorise skills [SKILL_ID] [--all] [--limit N]	List org skills, or show one's full instructions (read)

Destinations (--to)

Type is inferred from the file extension; --type overrides. Default destination is the reviewable inbox.

Extension	Type	Valid --to targets
pdf, docx, pptx, md, mdx, txt	document	inbox, collection, report
html, htm, xml	page	inbox, report
png, jpg, jpeg, svg, mp4	media	inbox, collection
csv, json	data	inbox, dataset
(--url)	link	inbox
(--text)	note	inbox, collection

--collection ID / --dataset ID imply the matching --to. Collection and dataset targets embed content and are metered — check algorise quota first. Over-cap ingests return HTTP 402; saturated org queues return HTTP 429.

MCP server

The bundled MCP server (algorise-mcp, stdio transport) exposes the same capabilities to in-editor agents. It reuses the CLI session in ~/.algorise/config.

Run algorise login once, then register the server.

Claude Code / Cursor (.mcp.json):

{
  "mcpServers": {
    "algorise": {
      "command": "uvx",
      "args": ["--from", "algorise", "algorise-mcp"]
    }
  }
}

If installed in a virtualenv, use "command": "algorise-mcp" instead.

Override API URL or token per server via env (ALGORISE_BRIDGE_API_URL, ALGORISE_BRIDGE_TOKEN). For multiple backends, register separate server entries with ALGORISE_BRIDGE_PROFILE in each env block.

MCP tools

Tool	Description
publish_note(text, title?, summary?, agent?)	Publish an inline markdown/MDX note
publish_artifact(..., to?, collection_id?, dataset_id?)	Publish content to a destination
post_update(artifact_id, body, review_requested?)	Post a progress update or request review
notify(title, message, action_url?)	Send a standalone notification
get_inbox(limit?)	List recently published artifacts (with previews)
get_quota()	Remaining ingest quota headroom
request_review(artifact_id, body)	Request a human review
get_artifact(artifact_id)	Fetch one artifact and its review state
list_artifact_replies(artifact_id, since?)	Replay an artifact's collaboration thread
pull_updates(agent_session_id, since?)	Poll a session for new replies

License

MIT