String

Install String (skill for AI agents)

You are reading this to learn how to install String and call String apps from any shell tool. Follow these steps in order.

1. Install

npm install -g @string-os/string

Requires Node.js 20+. The daemon (stringd) auto-starts on first call — no manual --daemon start needed. Verify:

string --help

2. The output frame

Every string call wraps stdout in:

<𝒞=string:<topic>>
...payload...
</𝒞>

Read the payload between the markers. The opener tells you which topic the call ran in.

3. Call shape

string <topic> '<command>'

A topic is the session label and scopes session state (current document, history, env vars).

Same topic = same state. The four hub names cannot be used as free-form labels.

4. Open an app and discover its actions

string app:weather '/open app:weather'

Response starts with the action menu:

[actions] now, forecast, search  ·  /act --help (all)  ·  /act.<name> --help

That line is your discovery output — every action the app exposes. For a single action's field schema, run /act.<name> --help; for every action on the doc at once, /act --help. Inside an app: topic, /open with no argument re-opens the app's home.

5. Run an action

string app:weather '/act.now --city Seoul'
# Positional (declaration order):
string app:weather '/act.now Seoul'
# Short alias if defined:
string app:weather '/act.now -c Seoul'
# Multi-word values — quote or use +:
string app:weather '/act.now "New York"'
string app:weather '/act.now New+York'
# Field schema:
string app:weather '/act.now --help'

Successful output:

<𝒞=string:app:weather>
seoul: Sunny +20°C ↘6km/h
</𝒞>

6. Install a new app

Paste a GitHub URL — the kind a browser address bar shows. The runtime enumerates the directory via the GitHub Contents API and installs every file:

string '/install https://github.com/string-os/apps/tree/main/apps/gh-kanban'

Short form (equivalent, less typing):

string '/install gh:string-os/apps/apps/gh-kanban'

Single-file app via raw or blob URL:

string '/install https://github.com/string-os/cookbook/blob/main/apps/weather/string.md'

From a local path:

string '/install --app ./apps/weather/string.md'

From any HTTPS URL (including install-manifest endpoints):

string '/install --app https://example.com/my-app/string.md'

The runtime copies files into the current agent's home, under packages/<name>/, and registers the app. Shell helpers shipped alongside (#!-prefixed scripts) are automatically marked executable. From this point on, app:<name> resolves from any session.

For heavy GitHub-install usage, export GITHUB_TOKEN (or GH_TOKEN) to lift the anonymous 60 req/hr rate limit to 5000 req/hr.

Available apps in the cookbook:

7. Set credentials

Apps that need API keys declare requires: [VAR_NAME] in frontmatter. When you /open an app without the var set, the response begins with:

[!] Missing required env: $MOLTBOOK_API_KEY
    Set: /set $MOLTBOOK_API_KEY = "..."
    Setup: /open requirements.md

Set the var with /set from the app topic:

string app:moltbook '/set $MOLTBOOK_API_KEY = "moltbook_xxx"'

Resolution cascades: config → app. There is no global fallback and no process.env fallback for action $VAR substitution, so one app cannot read another app's credentials.

8. Handle action errors

When an action fails and the app has a requirements.md, the error gets a trailing hint:

ERROR(EXIT_127): kubectl: command not found

Setup info: /open requirements.md

When you see that, run string app:<name> '/open requirements.md' to see what to install or configure. Then retry the action.

Reference

More

• Documentation
• Cookbook (example apps + walkthroughs)
• Source