GrepGuard CLI

Command line interface for GrepGuard.

Installation

npm install -g grepguard

After installation, you can use either grepguard or the shorter gg command:

grepguard auth login
gg auth login

Concepts

A namespace is a logical partition. Pods, also called sandboxes or containers, run inside that namespace.

Each pod is isolated from the other pods in the same namespace. Use a namespace to group pods, and use pods to run agents in separate sandboxed environments.

All pods run inside a namespace, and pod commands require a namespace.

The currently supported agents are opencode and codex.

Quick Start

Create an account and API key at GrepGuard, then follow these steps to run Codex in its first pod.

1. Log in:

gg auth login

Note: When prompted, paste the API key created on the GrepGuard website.

2. Create a namespace and check its status:

gg create namespace demo
gg get namespace

Note: Wait until the demo namespace status is active before continuing.

3. Create a pod:

gg create pod agent -n demo

4. Set the Codex API key:

gg env agent CODEX_API_KEY -n demo

Note: GrepGuard prompts for the key so it does not appear in your shell history.

5. Run Codex:

gg run agent -a codex -p "Clone https://github.com/grepguard/cli and explain the project." -n demo

6. Follow the agent's work:

gg logs agent -a codex -n demo

Commands

Log in with a GrepGuard API key:

grepguard auth login

Note: Create a GrepGuard account first, then create an API key on the website and paste it here.

Check whether an API key is saved locally:

grepguard auth status

List namespaces:

grepguard get namespace # or grepguard get ns

Create a namespace:

grepguard create namespace <name> # or grepguard create ns <name>

Delete a namespace:

grepguard delete namespace <name> # or grepguard delete ns <name>

List pods in a namespace:

grepguard get pods --namespace <namespace> # or grepguard get pods -n <namespace>

Create a pod in a namespace:

grepguard create pod <sandbox> --namespace <namespace> # or grepguard create pod <sandbox> -n <namespace>

Delete a pod in a namespace:

grepguard delete pod <sandbox> --namespace <namespace> # or grepguard delete pod <sandbox> -n <namespace>

Set one environment variable in a pod:

grepguard env <sandbox> <NAME> --namespace <namespace> # or grepguard env <sandbox> <NAME> -n <namespace>

Note: Set CODEX_API_KEY to authenticate Codex inside the pod, or set GIT_PAT so the agent can push to GitHub as Sandbar Agent. Set each variable in a separate command. GrepGuard securely prompts for the value so it does not appear in your shell history.

Run an agent in a sandbox:

grepguard run <sandbox> --agent <agent> --prompt <prompt> --namespace <namespace> # or grepguard run <sandbox> -a <agent> -p <prompt> -n <namespace>

Note: Agent is opencode or codex.

Show logs for an agent in a pod:

grepguard logs <sandbox> --agent <agent> --namespace <namespace> # or grepguard logs <sandbox> -a <agent> -n <namespace>

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.