Quickstart

The Modus CLI provides a set of commands to help you create, build, and run your Modus apps. Install the CLI using npm.

npm install -g @hypermode/modus-cli

To create a new Modus app, run the following command in your terminal:

modus new

This command prompts you to choose between Go and AssemblyScript as the language for your app. It then creates a new directory with the necessary files and folders for your app. You will also be asked if you would like to initialize a Git repository.

To build and run your app, navigate to the app directory and run the following command:

modus dev

This command runs your app locally in development mode and provides you with a URL to access your app’s generated API.

Once your app is running, you can access the graphical interface for your API at the URL located in your terminal.

View endpoint: http://localhost:8686/explorer

The API Explorer interface allows you to interact with your app’s API and test your functions.

Modus is a secure-by-default framework. To connect to external services, you need to add a connection in your app manifest.

Add the following code into your modus.json manifest file:

{
  "connections": {
    "zenquotes": {
      "type": "http",
      "baseUrl": "https://zenquotes.io/"
    }
  }
}

Functions are the building blocks of your app. Let’s add a function that fetches a random quote from the ZenQuotes connection you just created.

package main

import (
  "errors"
  "fmt"

  "github.com/hypermodeinc/modus/sdk/go/pkg/http"
)

type Quote struct {
  Quote  string `json:"q"`
  Author string `json:"a"`
}

// this function makes a request to an API that returns data in JSON format, and
// returns an object representing the data
func GetRandomQuote() (*Quote, error) {
  request := http.NewRequest("https://zenquotes.io/api/random")

  response, err := http.Fetch(request)
  if err != nil {
    return nil, err
  }
  if !response.Ok() {
    return nil, fmt.Errorf("Failed to fetch quote. Received: %d %s", response.Status, response.StatusText)
  }

  // the API returns an array of quotes, but we only want the first one
  var quotes []Quote
  response.JSON(&quotes)
  if len(quotes) == 0 {
    return nil, errors.New("expected at least one quote in the response, but none were found")
  }
  return &quotes[0], nil
}

package main

import (
  "errors"
  "fmt"

  "github.com/hypermodeinc/modus/sdk/go/pkg/http"
)

type Quote struct {
  Quote  string `json:"q"`
  Author string `json:"a"`
}

// this function makes a request to an API that returns data in JSON format, and
// returns an object representing the data
func GetRandomQuote() (*Quote, error) {
  request := http.NewRequest("https://zenquotes.io/api/random")

  response, err := http.Fetch(request)
  if err != nil {
    return nil, err
  }
  if !response.Ok() {
    return nil, fmt.Errorf("Failed to fetch quote. Received: %d %s", response.Status, response.StatusText)
  }

  // the API returns an array of quotes, but we only want the first one
  var quotes []Quote
  response.JSON(&quotes)
  if len(quotes) == 0 {
    return nil, errors.New("expected at least one quote in the response, but none were found")
  }
  return &quotes[0], nil
}

import { http } from "@hypermode/modus-sdk-as";

@json
class Quote {
  @alias("q")
  quote!: string;

  @alias("a")
  author!: string;
}

// this function makes a request to an API that returns data in JSON format, and
// returns an object representing the data
export function getRandomQuote(): Quote {
  const request = new http.Request("https://zenquotes.io/api/random");

  const response = http.fetch(request);
  if (!response.ok) {
    throw new Error(
      `Failed to fetch quote. Received: ${response.status} ${response.statusText}`,
    );
  }

  // the API returns an array of quotes, but we only want the first one
  return response.json<Quote[]>()[0];
}

export * from "./quotes";

After adding your function, you can use the API Explorer interface to test the GetRandomQuote function.

Modus also supports AI models. You can define new models in your modus.json file. Let’s add a new meta-llama model:

  "models": {
    "text-generator": {
      "sourceModel": "meta-llama/Llama-3.2-3B-Instruct",
      "provider": "hugging-face",
      "connection": "hypermode"
    }
  },

Next, install the Hyp CLI. This allows you to access hosted models on the Hypermode platform.

  npm install -g @hypermode/hyp-cli

You can now use the hyp login command to log in to the Hyp CLI. This links your project to the Hypermode platform, allowing you to leverage the model in your modus app.

When testing an AI app locally, Modus records the inference and related metadata in the View Inferences tab of the APIs explorer.