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:

>
...payload...

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

3. Call shape

string  ''

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

| Form | Use | |---|---| | ` | Free-form session — bare label you pick (e.g. main, notes, setup). Default when no topic is given is main. | | app: | Running an installed app | | app:: | Same app with a config-scoped env (e.g. app:weather:seoul for region-specific API key) | | bash: | Persistent shell session | | app, bash, tool, system | Hub topics — /open each for a one-call view: app lists installed apps + open app sessions, tool lists installed tools, bash lists active shells, system` shows daemon + home stats. Each page ends with the management commands for its kind. |

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. --help

That line is your discovery output — every action the app exposes. For a single action's field schema, run /act. --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:

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//, and registers the app. Shell helpers shipped alongside (#!-prefixed scripts) are automatically marked executable. From this point on, app: 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:

| App | What it does | Needs | |---|---|---| | weather | wttr.in wrapper: now, forecast, search | nothing | | moltbook | Multi-file social network demo (feed, posts, comments, profile) | API key | | moltbook-single | Same demo, single-file variant — for layout comparison | API key | | nano-banana-pro | Image generation via Gemini Nano Banana Pro | API key |

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"'

| Topic when running /set | Where it persists | |---|---| | free-form (main, notes, ...) | Not allowed for $VAR; use an app topic | | app: | App scope (apps//env.json) | | app:: | Config scope (apps///env.json) |

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: '/open requirements.md' to see what to install or configure. Then retry the action.

Reference

| Command | What it does | |---|---| | /open | Open document or app | | /open | Re-open current app's home (in app: topic) | | /back | Previous page | | /close | Close current document | | /refresh | Reload current document | | /info | Session state (current app, version, action list, history depth) | | /ls [path] | List files in a directory | | /help | All commands + current page actions | | /edit [#block] | View raw source; with body, edit file or block | | /write [#block] | Create or overwrite file/block | | /append | Append content to a file | | /replace | Replace exact text, block, line, or range | | /verify #block | Verify a block exists and show content | | /undo | Revert the last String edit | | /act. [flags] | Run action — positional or --flag value | | /act. --help | Field schema for that action | | /tool: [args] | Run an installed tool (default action) — POSIX CLI shape | | /tool:. [args] | Run a named action on a tool | | /install --app \| --tool | Install from local path or URL | | /uninstall | Remove installed package | | /set $VAR = "value" | Persistent app env var; run from app: | | /set | List session vars + persistent vars in scope |

More

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: string-os
• Source: string-os/string
• License: MIT
• Homepage: https://string-os.org

Install and usage instructions live in the source repository linked above.