mosoo-connector

Generated Go CLI for Mosoo integrators: Public Thread API, Console GraphQL, and console REST.

Build

make build

This clones or updates the Mosoo repository under .cache/mosoo, exports OpenAPI / GraphQL specs, renders specs/sources.yaml and overlays/*.yaml, runs Lathe code generation, and builds bin/mosoo. Generated CLI command indexes are rendered into publish/skills/mosoo/references/cli/; the CLI guide at publish/skills/mosoo/references/cli.md is rendered from Lathe Skill include resources under publish/skills/mosoo/lathe-include/; and the top-level Mosoo Skill entrypoint lives at publish/skills/mosoo/SKILL.md.

Lathe is managed by this repository. make build first compiles the pinned Lathe CLI from go.mod into .cache/bin/lathe, then uses that local binary for code generation.

Builds inject deterministic CLI version metadata from Git into Lathe's standard Version, Commit, and Date fields:

VERSION=$(git describe --tags --always --dirty)
COMMIT=$(git rev-parse --short=12 HEAD)
BUILD_DATE=$(git show -s --format=%cI HEAD)

Override VERSION, COMMIT, or BUILD_DATE for release builds when the release pipeline has already computed those values.

Override the API host base baked into per-module defaults:

make build MOSOO_HOST_BASE=https://api.example.com

Install

Install the latest published Go module without cloning the repository:

go install github.com/langgenius/mosoo-connector/cmd/mosoo@latest

Install a specific release:

go install github.com/langgenius/mosoo-connector/cmd/mosoo@vX.Y.Z

go install downloads the module source and compiles it locally. It does not run make build, so release tags include the generated CLI manifest and Go command sources needed by cmd/mosoo. Make sure go env GOBIN, or $(go env GOPATH)/bin when GOBIN is empty, is on PATH.

Install from a local checkout:

make install

By default, installation uses go env GOBIN, or $(go env GOPATH)/bin when GOBIN is empty. Override the destination with BINDIR:

make install BINDIR="$HOME/.bin"

make install runs make verify-install, which checks that the installed binary's mosoo --version output exactly matches the build metadata.

Homebrew

After a release's generated Homebrew formula pull request is merged, tap this repository and install the formula:

brew tap langgenius/mosoo-connector https://github.com/langgenius/mosoo-connector
brew install langgenius/mosoo-connector/mosoo

Release automation opens a GoReleaser pull request to add or update the formula. Merged formula revisions install the matching prebuilt mosoo archive from GitHub Releases.

Installer

The source for the Mosoo installer lives at publish/installers/install.sh. The current stable public entrypoint is:

curl -fsSL https://install.mosoo.ai/install.sh | bash

The installer is interactive by default and asks for y or n before high-impact steps. Use --yes for automation and --dry-run to preview the plan.

Published Skill layout

The publishable Mosoo Skill is rooted at publish/skills/mosoo.

publish/skills/mosoo/
|-- SKILL.md
`-- references/
    |-- setup.md
    |-- cli.md
    |-- api.md
    `-- cli/
        |-- catalog.md
        `-- modules/

references/cli.md, references/cli/catalog.md, and references/cli/modules/*.md are generated from Lathe's CLI Skill output during make build. To change the guide text in references/cli.md, edit the matching Lathe include file under lathe-include/. Treat the module files as CLI command indexes, not as the top-level Mosoo Skill.

Command layout

cli.command_path is namespaced: every generated command lives under its source module (console, console-rest, or public-thread-api). Root-level flat mounting is not used because the CLI ships three API surfaces.

Help text, examples, and error hints for generated commands come from overlays/*.yaml (regenerated by scripts/render-overlays.ts during make build). The generated catalog is the complete control-plane surface; overlays are usability polish, and the Mosoo Skill reference explains high-frequency workflows.

High-frequency root commands such as mosoo ls, mosoo run, mosoo add-key, and mosoo create-agent are Lathe overlay shortcuts for generated operations. They execute the same generated command specs as their canonical paths and are reported in the generated command catalog.

Hostnames and auth

Three API surfaces share one deployment but use different URL bases:

CLI module	Default hostname (from MOSOO_HOST_BASE)	Example paths
console, console-rest	{base}/api	/graphql, /access-tokens, /files
public-thread-api	{base}/api/v1	/agents/{id}/files, /agents/{id}/threads, /threads/{id}/events

Defaults are baked at codegen time (MOSOO_HOST_BASE, default http://127.0.0.1:8787). Override any command with --hostname or $MOSOO_HOST.

Target resolution

Generated API commands resolve a default target before falling back to baked-in hostnames. Explicit hostname overrides always win:

--hostname
  -> MOSOO_HOST
  -> --target / --base-url
  -> MOSOO_TARGET / MOSOO_BASE_URL
  -> project config .mosoo/config.json
  -> global config in the OS config dir (or $MOSOO_CONFIG_DIR/config.json)
  -> current directory looks like the Mosoo source repo
  -> default local target

Generated API commands still default to the local Mosoo development stack when no target config exists:

{
  "target": "local",
  "baseUrl": "http://127.0.0.1:8787"
}

First-time cloud users should use the zero-config setup and login path:

mosoo setup
mosoo auth login

mosoo setup stores the root target (https://try.mosoo.ai) in config. The CLI derives the console API (/api) and Public API (/api/v1) hosts internally. mosoo auth login defaults to Mosoo Cloud when no config exists, validates the token against the console API, and stores the same credential for both derived API hosts.

Self-hosted and local targets use explicit setup subcommands:

mosoo setup self-host --base-url https://mosoo.example.com
mosoo setup custom --api-url https://mosoo.example.com/api
mosoo setup local

Cloud and custom targets are also supported with explicit command flags:

mosoo doctor --json --target cloud
mosoo console user viewer --target custom --base-url https://example.com

Check the resolved target and readiness:

mosoo doctor --json

The JSON output is versioned with schemaVersion and groups machine-readable readiness data under target, auth, install, checks, and failures. Failure entries include stable code and action fields so automation can branch without parsing human messages.

For local development targets, the installer can sign in through the local development backdoor with an @mosoo.ai email, create a personal access token, and write the CLI credentials for both hostname bases. This only works against a loopback Mosoo API with the development backdoor enabled.

For cloud and custom targets, sign in at https://try.mosoo.ai or the configured web app, use a Mosoo API token from that logged-in web session, then run mosoo auth login. --hostname remains available as an advanced override for one-off host selection. The generated mosoo console-rest access create command maps to POST /access-tokens, but it still needs viewer-level authentication; it is not a first-login mechanism by itself.

Common commands

mosoo console user viewer
mosoo ls --app-limit 20 --agent-limit 20 --credential-limit 20 -o json
mosoo add-key --input-app-id <app-id> --input-vendor-id openai --input-name OpenAI --input-api-key-env OPENAI_API_KEY -o json
mosoo create-agent --file agent-create.json -o json
mosoo console agents publish --input-app-id <app-id> --input-agent-id <agent-id> -o json
mosoo run --input-app-id <app-id> --input-agent-id <agent-id> --input-prompt "Summarize this repository" -o json
mosoo console sessions events --app-id <app-id> --session-id <session-id> --limit 100 -o json
mosoo search "run agent" --json
mosoo commands show run --json

Use commands show before executing an unfamiliar generated command so flags, body shape, auth, and output format are explicit.

Public Thread file uploads

The Public API uses one multipart upload before a Thread references the file. Upload a local file to the Agent endpoint and save file.id from the response:

mosoo public-thread-api files upload \
  --agent-id <agent-id> \
  --file ./brief.txt \
  -o json

Then put that ID in resources[].file_id when creating a Thread or sending a follow-up user_message event:

{
  "input": {
    "content": [{ "type": "text", "text": "Summarize the attachment." }],
    "type": "user.message"
  },
  "resources": [{ "type": "file", "file_id": "<file-id>" }]
}

There is no public create-upload, PUT, complete, or post-create attach step. GET /threads/{threadId}/files lists claimed attachments and artifacts; metadata, content download, and deletion are exposed under /files/{fileId}.