Add readme

README.md

@@ -0,0 +1,219 @@
+# Metorial CLI
+
+Metorial CLI is the command line interface for Metorial. This CLI is built agent-first, meaning it is designed to be used both by developers directly and by agents that need to interact with Metorial resources and integrations.
+
+## Install
+
+Choose the install method that matches how you normally manage tools.
+
+### npm
+
+Best if you already use Node.js and want `metorial` available globally.
+
+```bash
+npm install -g @metorial/cli
+```
+
+### npx
+
+Best for one-off usage or quick checks without a global install.
+
+```bash
+npx @metorial/cli@latest
+```
+
+### Bash Installer
+
+Best on macOS and Linux if you want the standalone CLI without depending on Node.js.
+
+```bash
+curl -fsSL https://cli.metorial.com/install.sh | bash
+```
+
+### Homebrew
+
+Best if you already manage command line tools with Homebrew.
+
+```bash
+brew install metorial/tap/metorial
+```
+
+### Chocolatey
+
+Best for Windows setups that already use Chocolatey.
+
+```powershell
+choco install metorial
+```
+
+### Scoop
+
+Best for Windows setups that prefer Scoop.
+
+```powershell
+scoop bucket add metorial https://github.com/metorial/scoop-bucket
+scoop install metorial
+```
+
+### Start From An Example
+
+If you want to browse or create an official example project first:
+
+```bash
+npm create metorial@latest
+npm create metorial@latest <identifier> [path]
+```
+
+## Which Install Option Should I Use?
+
+- Use `npm` if you want a standard global install in a Node.js environment.
+- Use `npx` if you only need the CLI occasionally.
+- Use the bash installer if you want a simple standalone install on macOS or Linux.
+- Use `brew`, `choco`, or `scoop` if you already manage tools through that package manager.
+- Use `npm create metorial@latest` if your main goal is to begin with an official sample project.
+
+## Quick Start
+
+Install the CLI, then start here:
+
+```bash
+metorial login
+metorial providers list
+metorial deployments list
+metorial sessions list
+metorial integrations list
+metorial example list
+```
+
+If you want the dashboard as well:
+
+```bash
+metorial open
+```
+
+## Core Concepts In The CLI
+
+### Organizations, Projects, And Instances
+
+Metorial organizes work by organization, then project, then instance. In practice, an instance is usually the environment you are working against, such as development or production.
+
+When you browse resources in the CLI, you are usually looking at resources available in the current authenticated context and selected instance.
+
+### Providers
+
+Providers are the integrations you connect to Metorial. They define the tools, authentication methods, and configuration options available for a given integration.
+
+The CLI lets you inspect providers and related resources directly:
+
+```bash
+metorial providers list
+metorial providers get <provider-id>
+```
+
+### Deployments
+
+Deployments are the configured, ready-to-use instances of your providers. They are the core building blocks your applications use.
+
+Common commands:
+
+```bash
+metorial deployments list
+metorial deployments get <deployment-id>
+```
+
+### Sessions
+
+Sessions are the runtime layer that connects your application to one or more providers. A session exposes the tools from the attached providers and is useful for testing, debugging, and understanding how your runtime setup behaves.
+
+Common commands:
+
+```bash
+metorial sessions list
+metorial sessions get <session-id>
+```
+
+### Integrations
+
+Integrations help you discover, set up, and manage the providers available through Metorial.
+
+Common commands:
+
+```bash
+metorial integrations list
+metorial integrations catalog list
+metorial integrations get <integration-id>
+```
+
+## Main Commands
+
+### Sign In
+
+```bash
+metorial login
+```
+
+Starts the sign-in flow and saves your profile locally so the CLI can act on your behalf.
+
+### Explore Your Resources
+
+```bash
+metorial providers list
+metorial deployments list
+metorial sessions list
+metorial instance list
+```
+
+This is the fastest way to understand what is available in your account and environment.
+
+### Work With Integrations
+
+```bash
+metorial integrations list
+metorial integrations catalog list
+metorial integrations tools <integration-id>
+```
+
+Use these commands to review connected integrations, browse the catalog, and inspect the tools exposed by an integration.
+
+### Start From Official Examples
+
+```bash
+metorial example list
+metorial example create <identifier>
+```
+
+Use examples when you want a working starting point instead of beginning from scratch.
+
+Examples are also available through `npm create`.
+
+```bash
+npm create metorial@latest
+npm create metorial@latest <identifier> [path]
+```
+
+### Send Authenticated API Requests
+
+```bash
+metorial fetch <path-or-url>
+```
+
+Useful when you want to inspect an API response directly from the terminal while keeping the same authenticated context.
+
+## Help
+
+Use built-in help to discover commands as you go:
+
+```bash
+metorial --help
+metorial <command> --help
+```
+
+## Learn More
+
+- [Metorial docs](https://metorial.com/docs)
+- [Providers](https://metorial.com/docs/concepts-providers)
+- [Server deployments](https://metorial.com/docs/concepts-server-deployments)
+- [Sessions](https://metorial.com/docs/concepts-sessions)
+- [Projects and organizations](https://metorial.com/docs/concepts-projects-organizations)
+
+For a shorter install-first guide, see `cli.metorial.com/cli.md` in this repository or visit [cli.metorial.com](https://cli.metorial.com).

cli.metorial.com/cli.md

@@ -0,0 +1,178 @@
+# Metorial CLI
+
+Metorial CLI is the simplest way to work with Metorial from your terminal.
+
+It helps you:
+
+- sign in to your Metorial account
+- inspect providers, deployments, sessions, and other resources
+- browse and manage integrations
+- send authenticated API requests
+- start from official example projects
+
+If you are new to Metorial, the core idea is simple: Metorial helps you deploy and manage providers for AI applications. The CLI gives you a direct way to explore those providers, inspect your deployments, and work with runtime sessions from the command line.
+
+## Install
+
+Pick the option that matches your setup.
+
+### macOS or Linux
+
+Use the standalone installer:
+
+```bash
+curl -fsSL https://cli.metorial.com/install.sh | bash
+```
+
+### npm
+
+Use npm if you already work in Node.js:
+
+```bash
+npm install -g @metorial/cli
+```
+
+### npx
+
+Use npx if you want to run the CLI without installing it globally:
+
+```bash
+npx @metorial/cli@latest
+```
+
+### Homebrew
+
+```bash
+brew install metorial/tap/metorial
+```
+
+### Chocolatey
+
+```powershell
+choco install metorial
+```
+
+### Scoop
+
+```powershell
+scoop bucket add metorial https://github.com/metorial/scoop-bucket
+scoop install metorial
+```
+
+## Which Install Option Should I Pick?
+
+- Use the installer for a simple standalone install on macOS or Linux.
+- Use `npm` if you want a normal global install in a Node.js environment.
+- Use `npx` if you only need the CLI occasionally.
+- Use `brew`, `choco`, or `scoop` if that is already how you manage tools.
+
+## Understand The Basics
+
+You do not need to memorize the full Metorial model to get started, but these terms help:
+
+- A provider is an integration such as Slack, GitHub, Exa, or another tool source.
+- A deployment is the configured instance of that provider that your app can use.
+- A session is the runtime layer that gives your AI access to tools from one or more attached providers.
+- An organization, project, and instance help you separate work and environments such as development and production.
+
+## First Steps
+
+Sign in first:
+
+```bash
+metorial login
+```
+
+Then inspect what is available in your account:
+
+```bash
+metorial providers list
+metorial deployments list
+metorial sessions list
+metorial integrations list
+```
+
+If you want the dashboard too:
+
+```bash
+metorial open
+```
+
+## Core Commands
+
+### Sign In
+
+```bash
+metorial login
+```
+
+Starts the browser-based sign-in flow and makes that profile active on your machine.
+
+### Browse Resources
+
+```bash
+metorial providers list
+metorial deployments list
+metorial sessions list
+metorial instance list
+```
+
+These commands help you understand your current setup, especially when you are checking what providers and deployments are available in a given environment.
+
+### Work With Integrations
+
+```bash
+metorial integrations list
+metorial integrations catalog list
+metorial integrations tools <integration-id>
+```
+
+Use these commands to inspect connected integrations, browse the catalog, and see the tools an integration exposes.
+
+### Start From An Example
+
+```bash
+metorial example list
+metorial example create <identifier>
+```
+
+You can also do this through npm:
+
+```bash
+npm create metorial@latest
+npm create metorial@latest <identifier> [path]
+```
+
+### Open Metorial In Your Browser
+
+```bash
+metorial open
+```
+
+### Send An Authenticated API Request
+
+```bash
+metorial fetch <path-or-url>
+```
+
+Useful when you want a direct API response from the same authenticated context you are already using in the CLI.
+
+### Check Your Version
+
+```bash
+metorial version
+```
+
+## Need More?
+
+```bash
+metorial --help
+metorial <command> --help
+```
+
+Docs:
+
+- [Metorial docs](https://metorial.com/docs)
+- [Providers](https://metorial.com/docs/concepts-providers.md)
+- [Server deployments](https://metorial.com/docs/concepts-server-deployments.md)
+- [Sessions](https://metorial.com/docs/concepts-sessions.md)