shsf-cli/README.md

SHSF CLI

Production-ready command-line tooling for SHSF instances. The CLI manages functions, namespaces, files, triggers, storage, environment variables, CORS, execution, logs, rate limits, and exposes the live SHSF REST and MCP surfaces for agents.

Requirements

• Node.js 22 or newer
• pnpm 10 or newer
• An SHSF access token

Install

pnpm add -g shsf-cli

From source:

pnpm install
pnpm build
pnpm start -- health

Configuration

The CLI reads configuration in this order:

1. SHSF_INSTANCE and SHSF_TOKEN environment variables.
2. ~/.shsf_config, created interactively on first use.

Example non-interactive configuration:

export SHSF_INSTANCE=https://shsf.example.com
export SHSF_TOKEN=token_xxx
shsf health

Core Commands

shsf health
shsf uiurl
shsf create namespace --name apps
shsf create function --name api --description "API handler" --image python:3.13 --startup-file main.py --namespace-id 1 --allow-http true
shsf update function 42 --cache-enabled true --cache-ttl 60 --network-restricted true
shsf get function 42
shsf get exec-url --id 42
shsf function execute --id 42 --payload '{"name":"Ada"}' --route users/list --method POST --no-stream

Files can be synchronized from a local directory:

shsf remote push --id 42 --from ./functions/api --force
shsf remote pull --id 42 --to ./functions/api

Use .shsfignore for gitignore-style push exclusions and .shsf.json for local mappings:

{
  "default": {
    "id": "42",
    "from": "functions/api"
  }
}

Current SHSF Features

Typed commands cover the common stable workflows:

• create|get|update|delete namespace
• create|get|update|delete function
• function execution, dependency install, logs, logging config, rate-limit config
• file create/list/rename/delete
• trigger create/get/update/delete plus run-now
• storage create/list/delete, item get/set/delete/clear
• function and account-level environment variables
• CORS origin list/add/remove/clear
• function counts and health checks

The live backend also exposes admin, global settings, Git source, import/replace, guest, AI, account export, OpenAPI, and MCP routes. Use shsf api request for any route without a specialized wrapper:

shsf api openapi
shsf api request GET /api/functions
shsf api request PATCH /api/function/42/logging --data '{"enabled":true,"hide_payload_headers":true}'
shsf api request POST /api/function/42/git/pull

Agent Use

SHSF exposes an MCP server at /mcp. The CLI has direct wrappers for agent bootstrap and tool calls:

shsf mcp info
shsf mcp init
shsf mcp tools
shsf mcp docs
shsf mcp call list_functions --args '{"namespace":"apps"}'
shsf mcp call write_file --args '{"id":42,"filename":"main.py","content":"def main(args): return {\"ok\": True}"}'

Agents should call shsf mcp docs before writing SHSF function code. The docs include runtime entry points, args shape, v2 response envelope, routing, dependencies, storage, and absolute platform rules.

CI/CD

This repository uses Gitea Actions in .gitea/workflows/ci.yml.

• Build job: checkout, pnpm setup, Node 24, pnpm-store cache, install, test, build, package artifact.
• Publish job on main: rebuilds, publishes to npm when NPM_TOKEN is configured, and creates a Gitea release when GITEA_TOKEN is configured.

GitHub Actions and Copilot-specific instructions were removed.

Development

pnpm test
pnpm build
pnpm test:coverage

Add a command by creating a file under src/commands. Export an object with name, description, optional options, and action. Directory names become command groups automatically.

License

MIT-0