# semantius The official CLI for the [Semantius](https://semantius.com) platform. Connect to your Semantius organization's MCP servers to interact with your data, tools, and APIs directly from the command line or AI agents. ## Features - 🪶 **Lightweight** - Minimal dependencies, fast startup - 🔧 **Shell-Friendly** - JSON output for call, pipes with `jq`, chaining support - 🤖 **Agent-Optimized** - Designed for AI coding agents (Gemini CLI, Claude Code, etc.) - 🔌 **Semantius Platform** - Connects to your Semantius organization's `crud` and `cube` MCP servers - ⚡ **Fast** - Connections and tokens are cached between calls, so repeated invocations stay responsive - 🔑 **Zero Config** - Works out of the box with `SEMANTIUS_API_KEY` and `SEMANTIUS_ORG` set - 💡 **Actionable Errors** - Structured error messages with available servers and recovery suggestions ## Quick Start ### 1. Installation **Linux / macOS:** ```bash curl -fsSL https://raw.githubusercontent.com/semantius/semantius-cli/main/install.sh | bash ``` The Linux/macOS installer places `semantius` in `/usr/local/bin` (if writable), otherwise `~/.local/bin`, and adds it to your PATH automatically. **Windows (PowerShell):** ```powershell irm https://raw.githubusercontent.com/semantius/semantius-cli/main/install.ps1 | iex ``` The Windows installer places `semantius.exe` in `%LOCALAPPDATA%\Programs\Semantius` and adds it to your user PATH automatically. ### 2. Set up credentials Set your Semantius credentials. The CLI looks for a `.env` file in the current directory, then next to the executable (Windows), or you can export them in your shell. Shell environment variables always take precedence over `.env` values. ```bash # Option 1: Export in shell export SEMANTIUS_API_KEY=your-api-key export SEMANTIUS_ORG=your-org-name # Option 2: .env file (current directory first, then next to the executable) # SEMANTIUS_API_KEY=your-api-key # SEMANTIUS_ORG=your-org-name ``` The CLI automatically connects to your Semantius MCP servers (`crud` and `cube`) — no config file needed. ### 3. Discover available tools ```bash # List all servers and tools semantius # With descriptions semantius -d ``` ### 4. Call a tool ```bash # View tool schema first semantius info crud # Call a tool semantius call crud list_records '{}' ``` ## Usage ``` semantius [options] List all servers and tools semantius [options] info Show server tools and parameters semantius [options] info Show tool schema semantius [options] grep Search tools by glob pattern semantius [options] call Call tool (reads JSON from stdin if no args) semantius [options] call Call tool with JSON arguments semantius [options] ping [-n [count]] Check connectivity & latency to crud/getCurrentUser semantius [options] whoami Show current user (email, org, roles) ``` **Both formats work:** `info ` or `info /` > [!TIP] > Add `-d` to any command to include descriptions. ### Options | Option | Description | |--------|-------------| | `-h, --help` | Show help message | | `-v, --version` | Show version number | | `-d, --with-descriptions` | Include tool descriptions | | `-md, --markdown` | Dump full documentation as markdown (README, SKILL, all tools) | | `-n [count]` | (ping only) Run N pings and report per-request latency + min/max/avg. `-n` without a value defaults to 5 | | `--disable-jwt-cache` | Skip the token cache and re-authenticate on every request (see [Token cache](#token-cache)) | ### Output | Stream | Content | |--------|---------| | **stdout** | Tool results and human-readable info | | **stderr** | Errors and diagnostics | ### Commands #### List Servers ```bash # Basic listing $ semantius github • search_repositories • get_file_contents • create_or_update_file filesystem • read_file • write_file • list_directory # With descriptions $ semantius --with-descriptions github • search_repositories - Search for GitHub repositories • get_file_contents - Get contents of a file or directory filesystem • read_file - Read the contents of a file • write_file - Write content to a file ``` #### Search Tools ```bash # Find file-related tools across all servers $ semantius grep "*file*" github/get_file_contents github/create_or_update_file filesystem/read_file filesystem/write_file # Search with descriptions $ semantius grep "*search*" -d github/search_repositories - Search for GitHub repositories ``` #### View Server Details ```bash $ semantius info github Server: github Transport: stdio Command: npx -y @modelcontextprotocol/server-github Tools (12): search_repositories Search for GitHub repositories Parameters: • query (string, required) - Search query • page (number, optional) - Page number ... ``` #### View Tool Schema ```bash # Both formats work: $ semantius info github search_repositories $ semantius info github/search_repositories Tool: search_repositories Server: github Description: Search for GitHub repositories Input Schema: { "type": "object", "properties": { "query": { "type": "string", "description": "Search query" }, "page": { "type": "number" } }, "required": ["query"] } ``` #### Call a Tool ```bash # With inline JSON $ semantius call github search_repositories '{"query": "mcp server", "per_page": 5}' # JSON output is default for call command $ semantius call github search_repositories '{"query": "mcp"}' | jq '.content[0].text' # Read JSON from stdin (no '-' needed!) $ echo '{"path": "./README.md"}' | semantius call filesystem read_file ``` #### Complex Commands For JSON arguments containing single quotes, special characters, or long text, use **stdin** to avoid shell escaping issues: ```bash # Using a heredoc (no '-' needed with call subcommand) semantius call server tool < main.ts # 6. Error handling in scripts if result=$(semantius call filesystem read_file '{"path": "./config.json"}' 2>/dev/null); then echo "$result" | jq '.content[0].text | fromjson' else echo "File not found, using defaults" fi # 7. Aggregate results from multiple servers { semantius call github search_repositories '{"query": "mcp", "per_page": 3}' semantius call filesystem list_directory '{"path": "./src"}' } | jq -s '.' ``` **Tips for chaining:** - Use `jq -r` for raw output (no quotes) - Use `jq -e` for conditional checks (exit code 1 if false) - Use `2>/dev/null` to suppress errors when testing - Use `| jq -s '.'` to combine multiple JSON outputs ## Configuration ### Environment Variables All env vars use a configurable prefix (default `SEMANTIUS_`). Pass `--env ` to switch — e.g. `--env PROD` reads `PROD_API_KEY`, `PROD_TIMEOUT`, `PROD_LOG_FILE`, etc., so you can keep separate DEV/STAGE/PROD configurations side by side in the same `.env`. | Variable | Description | Default | |----------|-------------|---------| | `SEMANTIUS_API_KEY` | API key for Semantius (**required**) | (none) | | `SEMANTIUS_ORG` | Organization name for Semantius (**required**) | (none) | | `SEMANTIUS_CONFIG_PATH` | Path to config file | (none) | | `SEMANTIUS_DEBUG` | Enable debug output | `false` | | `SEMANTIUS_TIMEOUT` | Request timeout (seconds) | `1800` (30 min) | | `SEMANTIUS_CONCURRENCY` | Servers processed in parallel (not a limit on total) | `5` | | `SEMANTIUS_MAX_RETRIES` | Retry attempts for transient errors (0 = disable) | `3` | | `SEMANTIUS_RETRY_DELAY` | Base retry delay (milliseconds) | `1000` | | `SEMANTIUS_STRICT_ENV` | Error on missing `${VAR}` in config | `true` | | `SEMANTIUS_NO_DAEMON` | Disable connection caching; open a fresh connection per call (Linux/macOS only — no-op on Windows) | `false` | | `SEMANTIUS_DAEMON_TIMEOUT` | How long a cached connection stays open after last use (seconds, Linux/macOS only) | `60` | | `SEMANTIUS_DISABLE_JWT_CACHE` | Disable the encrypted token cache; re-authenticate on every request | `false` | | `SEMANTIUS_LOG_FILE` | Append one JSONL line per invocation to this path. Bare filename is written next to the loaded `.env` (or in the user config dir); absolute/relative paths are used as-is. | (none) | | `SEMANTIUS_LOG_LEVELS` | Comma-separated subset of `{all, error, slow, jwt}` that filters which invocations are logged. `error` = exit code != 0; `slow` = wall time > 1000 ms; `jwt` = error mentions "JWT" (also adds a structured `jwt` field with the token value and appends one JSONL line per JWT-retry attempt). Multiple values OR-combine (e.g. `error,slow`). Unknown/empty falls back to `all`. | `all` | ### Token cache By default, the CLI exchanges your API key for a short-lived token on first use and caches it for subsequent requests, so every call after the first is significantly faster. The token is refreshed automatically before it expires. The cache lives in your OS temp directory (`/tmp` on Linux/macOS, `%TEMP%` on Windows) and is encrypted with a key derived from your API key secret — a cache file alone, without the API key, cannot be used to authenticate. To disable the cache and re-authenticate on every call, pass `--disable-jwt-cache` or set `SEMANTIUS_DISABLE_JWT_CACHE=1`. Disabling degrades performance and should only be used when your threat model forbids any credential-derived material on disk, or when running in a read-only container where the cache file cannot be written anyway. ## Using with AI Agents `semantius` gives AI coding agents direct access to your Semantius platform's tools and data through the MCP protocol. The CLI approach is token-efficient — schemas are only fetched on demand. ### Why CLI? - **On-demand loading**: Only fetch schemas when needed - **Token efficient**: Minimal context overhead - **Shell composable**: Chain with `jq`, pipes, and scripts - **Scriptable**: AI can write shell scripts for complex workflows ### Option 1: System Prompt Integration Add this to your AI agent's system prompt for direct CLI access: ````xml ## Semantius Platform You have access to the Semantius platform via the `semantius` CLI. Commands: ```bash semantius info # List all servers semantius info # Show server tools semantius info # Get tool schema semantius grep "" # Search tools semantius call # Call tool (stdin auto-detected) semantius call '{}' # Call with JSON args ``` **Both formats work:** `info ` or `info /` Workflow: 1. **Discover**: `semantius info` to see available servers 2. **Inspect**: `semantius info ` to get the schema 3. **Execute**: `semantius call '{}'` with arguments ### Examples ```bash # List available tools semantius info crud # Call with inline JSON semantius call crud list_records '{}' # Pipe from stdin (no '-' needed) echo '{"id": "123"}' | semantius call crud get_record # Heredoc for complex JSON semantius call crud create_record <= 1.0.0 ### Setup ```bash git clone https://github.com/semantius/semantius-cli.git cd semantius bun install ``` ### Commands ```bash # Run in development bun run dev # Type checking bun run typecheck # Linting bun run lint bun run lint:fix # Run all tests (unit + integration) bun test # Run only unit tests (fast) bun test tests/config.test.ts tests/output.test.ts tests/client.test.ts # Run integration tests (requires MCP server, ~35s) bun test tests/integration/ # Build single executable bun run build # Build for all platforms bun run build:all ``` ### Local Testing & Debugging There are three ways to run the CLI while iterating on a change — pick whichever matches what you're trying to verify. #### 1. `bun run dev` — fastest feedback loop `bun run dev` runs `src/index.ts` directly via Bun; no build step, no link. Just pass the same args you'd give the installed binary: ```bash # Basic commands bun run dev --help bun run dev info crud bun run dev whoami bun run dev ping bun run dev ping -n # 5 pings + min/max/avg bun run dev ping -n 20 # 20 pings + min/max/avg bun run dev grep "*record*" bun run dev call crud getCurrentUser '{}' # Pipe JSON in via stdin echo '{}' | bun run dev call crud getCurrentUser ``` Required env vars (`SEMANTIUS_API_KEY`, `SEMANTIUS_ORG`) are picked up from your shell or from a `.env` next to the binary / in the user config dir. Use `--env ` to test a different credential set (e.g. `--env STAGING` reads `STAGING_API_KEY` / `STAGING_ORG`). #### 2. Verbose / debug output ```bash # Bash / macOS / Linux SEMANTIUS_DEBUG=1 bun run dev ping # PowerShell $env:SEMANTIUS_DEBUG=1; bun run dev ping ``` Debug mode prints daemon spawn decisions, MCP transport activity, and underlying error messages that are normally hidden behind the friendly `Error [CODE]: …` output. To bypass the connection cache and see raw per-call latency (also the default on Windows): ```bash SEMANTIUS_NO_DAEMON=1 bun run dev ping -n 5 ``` #### 3. Step-through debugging with the Bun inspector ```bash bun --inspect-brk src/index.ts ping ``` Bun prints a `chrome-devtools://…` URL on startup. Open it in Chrome, or attach VS Code's built-in **Bun: Attach** launch config. Set breakpoints in [src/commands/identity.ts](src/commands/identity.ts) (for `ping` / `whoami`), [src/commands/call.ts](src/commands/call.ts), or [src/client.ts](src/client.ts) to step through transport handling. #### 4. As the installed binary (`bun link`) To test the exact UX the user gets — including how Bun resolves the shebang and how PATH lookup works — link the package globally: ```bash # Link once; now `semantius` resolves to your working tree bun link semantius --help semantius ping -n 10 # Unlink when done bun unlink ``` #### 5. Automated tests ```bash # All tests (unit + integration; integration hits real MCP servers ~35s) bun test # Fast unit-only loop bun test tests/config.test.ts tests/output.test.ts tests/client.test.ts # Integration only bun test tests/integration/ ``` Integration tests need valid `SEMANTIUS_API_KEY` / `SEMANTIUS_ORG` and a reachable platform; they skip automatically when the server is unreachable. ### Releasing Releases are automated via GitHub Actions. Use the release script: ```bash ./scripts/release.sh 0.2.0 ``` ### Error Messages All errors include actionable recovery suggestions, optimized for both humans and AI agents: ``` Error [AMBIGUOUS_COMMAND]: Ambiguous command: did you mean to call a tool or view info? Details: Received: semantius filesystem read_file Suggestion: Use 'semantius call filesystem read_file' to execute, or 'semantius info filesystem read_file' to view schema Error [UNKNOWN_SUBCOMMAND]: Unknown subcommand: "run" Details: Valid subcommands: info, grep, call Suggestion: Did you mean 'semantius call'? Error [SERVER_NOT_FOUND]: Server "github" not found in config Details: Available servers: filesystem, sqlite Suggestion: Use one of: semantius info filesystem, semantius info sqlite Error [TOOL_NOT_FOUND]: Tool "search" not found in server "filesystem" Details: Available tools: read_file, write_file, list_directory (+5 more) Suggestion: Run 'semantius info filesystem' to see all available tools Error [INVALID_JSON_ARGUMENTS]: Invalid JSON in tool arguments Details: Parse error: Unexpected identifier "test" Suggestion: Arguments must be valid JSON. Use single quotes: '{"key": "value"}' ``` ## License MIT License - see [LICENSE](LICENSE) for details. ## Contributing Contributions are welcome! Please feel free to submit a Pull Request.

semantius-modeler

Installation

SKILL.md