Agent setup with the CLI

The CLI is published as @vibelabsdotto/featurama-cli. It needs Node.js 22 or newer and an instance with the stateless /mcp endpoint. It prints JSON on stdout and JSON errors on stderr, with a nonzero exit code. An interactive terminal also has a React/Ink context picker when you run it without arguments.

Use the scoped npm name. The unscoped featurama package belongs to someone else. npx featurama is safe only after you install @vibelabsdotto/featurama-cli locally in that project; otherwise run the scoped command below.

One-time setupCopy Anchor Link

The account owner must first create an agent token in Settings. Have a trusted secret manager supply it to the agent through a private stdin stream or the FEATURAMA_TOKEN environment variable. Do not paste the token into chat or shell arguments.

These commands target the Preview API at newapi.featurama.app. For self-hosting, replace it with your HTTPS API origin. Do not append /mcp.

npx -y @vibelabsdotto/featurama-cli@0.1.3 --help
npx -y @vibelabsdotto/featurama-cli@0.1.3 context add preview --instance https://newapi.featurama.app --use
npx -y @vibelabsdotto/featurama-cli@0.1.3 login --token-stdin < /secure/path/to/agent-token
npx -y @vibelabsdotto/featurama-cli@0.1.3 context verify preview
npx -y @vibelabsdotto/featurama-cli@0.1.3 projects list

/secure/path/to/agent-token is an example path supplied by your secret manager, not a file the CLI creates. login validates the token against the selected instance before saving it. context verify checks authentication and MCP tool discovery without creating a project. Stop on a nonzero exit code; do not continue with another instance's token.

If your automation injects FEATURAMA_TOKEN, you can run login without --token-stdin. For one-off commands, the environment variable overrides the saved token without changing it.

Work with projectsCopy Anchor Link

List before creating. Lifetime access is required to create any project, and a successful create returns the project API key once on stdout. Do not send or save that response in shared logs or chat. Arrange a secure handoff to the mobile app's build configuration, then remove the key from the agent's transient output.

npx -y @vibelabsdotto/featurama-cli@0.1.3 projects list
# Only after unlocking lifetime access:
npx -y @vibelabsdotto/featurama-cli@0.1.3 projects create --name 'My app' --technology expo
npx -y @vibelabsdotto/featurama-cli@0.1.3 projects get <projectId>
npx -y @vibelabsdotto/featurama-cli@0.1.3 projects update --project-id <projectId> --email-collection optional
npx -y @vibelabsdotto/featurama-cli@0.1.3 requests list --project-id <projectId> --status Roadmap --page 1 --page-size 20

projects update changes only email collection. Use none, optional, or required, then read the project back. The server must expose updateProject; older instances cannot accept this command.

projects get returns the key prefix, not the full existing key. Business commands return an MCP JSON envelope. Read the result from content[0].text or structuredContent, not from the outer object. A request created with requests create is approved automatically. Status values are Requested, Roadmap, InProgress, Done, and Declined. Use --help for all commands and flags. Do not automatically retry a timed-out write; check its result first because it may have succeeded.

Read and reply to commentsCopy Anchor Link

A reply is public. App users see it under the request with the Developer badge, and if the submitter left an email address, Featurama also sends them a reply email. Replies cannot be edited. An individual comment can be deleted, but an email already sent cannot be recalled. Never post secrets or internal notes.

npx -y @vibelabsdotto/featurama-cli@0.1.3 requests comments --project-id <projectId> --request-id <requestId>
npx -y @vibelabsdotto/featurama-cli@0.1.3 requests reply --project-id <projectId> --request-id <requestId> --content 'Thanks for the idea. Dark mode is now on our roadmap.'

requests comments returns the request's comments, oldest first. Read them before replying. requests reply posts as the developer who owns the token, the same as a reply from the dashboard. --content must not be blank and can be up to 10,000 characters. If a reply times out, run requests comments before sending it again, or the user may get the same reply twice.

Delete one commentCopy Anchor Link

Read the comments first and copy the exact ID of the comment you intend to remove.

npx -y @vibelabsdotto/featurama-cli@0.1.3 requests delete-comment --project-id <projectId> --request-id <requestId> --comment-id <commentId>
npx -y @vibelabsdotto/featurama-cli@0.1.3 requests comments --project-id <projectId> --request-id <requestId>

The project must belong to the developer who owns the token. The command removes only that comment and its comment votes, and updates the comment count. The request, its votes and all other comments remain. Deletion cannot be undone and does not recall sent emails. If deletion times out, read the comments again before retrying.

Multiple instancesCopy Anchor Link

npx -y @vibelabsdotto/featurama-cli@0.1.3 context add selfhosted --instance https://api.example.com
npx -y @vibelabsdotto/featurama-cli@0.1.3 context list
npx -y @vibelabsdotto/featurama-cli@0.1.3 --context selfhosted projects list
npx -y @vibelabsdotto/featurama-cli@0.1.3 context use selfhosted

context add saves a name and origin; the first context becomes the default, and context use changes it. The command-level --context NAME does not change the default. Log in separately for each origin. --instance URL selects a one-off origin without saving a context. HTTPS is required except for a literal loopback IP over HTTP, such as http://127.0.0.1:3000. A context URL cannot contain a path, query, credentials, or fragment.

Instance resolution order is --instance or --context, then FEATURAMA_INSTANCE, then FEATURAMA_CONTEXT, then the saved default. Explicit --instance and --context cannot be combined. The token stays bound to its origin; deleting a context does not revoke a token. Revoke it in Settings if it should no longer work.

The CLI stores credentials as plaintext in $XDG_CONFIG_HOME/featurama/config.json or ~/.config/featurama/config.json, protected by directory permissions 0700 and file permissions 0600. Keep the file out of repositories, backups shared with other users, and support tickets. The CLI reads earlier single-instance config and upgrades it when you change contexts; it preserves existing tokens by origin.

Next stepsCopy Anchor Link

• Install the SDK with a project key from this same instance.
• Connect MCP directly if your agent already has an HTTP MCP client.
• Troubleshooting for authentication, URL, and project-visibility errors.