CLI Commands

The opengram CLI manages server setup, startup, and system service integration. It is installed globally via npm or the install script.

`opengram init`

Interactive setup wizard that walks through initial configuration.

opengram init

The wizard prompts for:

Server port -- the HTTP port Opengram listens on
Base URL -- the public URL used for push notifications and webhooks
Instance secret -- generates a secure og_-prefixed token for API authentication
Auto-rename -- configure automatic chat title generation with an LLM provider
OpenClaw plugin -- optionally set up the OpenClaw agent plugin
background service -- optionally install a system service for automatic startup (Linux systemd and macOS launchd)

Configuration is written to ~/.opengram/opengram.config.json (or $OPENGRAM_HOME/opengram.config.json). The wizard auto-detects the Tailscale hostname (if available) and suggests it as the default base URL.

`opengram start`

Start the Opengram server.

opengram start
opengram start --port 8080

Flag	Description
`--port N`	Override the port from the configuration file (sets the `OPENGRAM_SERVER_PORT` env var)

The server runs in the foreground. Use opengram service install or Docker for production deployments that should survive terminal closure.

When starting, the CLI automatically sets these environment variables:

Variable	Value
`NODE_ENV`	`production`
`DATABASE_URL`	`<dataDir>/opengram.db`
`OPENGRAM_DATA_ROOT`	`<dataDir>`
`OPENGRAM_MIGRATIONS_DIR`	`<pkgRoot>/migrations`
`OPENGRAM_CONFIG_PATH`	`<home>/opengram.config.json` (if the file exists)

Where <home> is $OPENGRAM_HOME (default: ~/.opengram) and <dataDir> is <home>/data.

`opengram stop`

Stop the background service. This is a shortcut for opengram service stop.

opengram stop

On Linux, this runs systemctl --user stop opengram. On macOS, it uses launchctl stop to stop the launchd agent.

`opengram restart`

Restart the background service. This is a shortcut for opengram service restart.

opengram restart

On Linux, this runs systemctl --user restart opengram. On macOS, it uses launchctl kickstart -k to restart the launchd agent.

`opengram upgrade`

Upgrade Opengram to the latest version.

opengram upgrade

This command:

Detects your package manager (pnpm, bun, or npm)
Runs <pkg-mgr> install -g @opengramsh/opengram@latest
If the background service is running, restarts it automatically
Prints the version change (e.g. Upgraded: v0.1.0 → v0.2.0)

`opengram service`

Manage the background service. Supported on Linux (systemd) and macOS (launchd). On other platforms, use opengram start directly or a process manager like pm2.

opengram service <action>

Action	Description
`install`	Create and enable the service. The service starts on boot and restarts automatically on failure
`uninstall`	Stop and remove the service
`start`	Start the service
`stop`	Stop the service without removing it
`restart`	Restart the service
`status`	Show whether the service is running and recent log output
`logs`	Stream live log output from the service (`journalctl --user-unit opengram -f` on Linux, `tail -f ~/.opengram/logs/stdout.log` on macOS)

`opengram version`

Print the installed Opengram version.

opengram version
opengram --version
opengram -v

`opengram help`

Show available commands and usage information.

opengram help
opengram --help
opengram -h

On this page