feat(logs): streaming foundation, new log flags, and vcr logs alias

docs/vcr.md

@@ -5,17 +5,68 @@ Streamline your Vonage Cloud Runtime development and management tasks with VCR
 ### Synopsis
 
 VCR CLI is a powerful command-line interface designed to streamline
-and simplify the development and management of applications on 
+and simplify the development and management of applications on
 the Vonage Cloud Runtime platform.
 
+Vonage Cloud Runtime (VCR) enables you to build, deploy, and run serverless
+applications that integrate with Vonage communication APIs including Voice,
+Messages, and RTC (Real-Time Communication).
+
+GETTING STARTED
+  1. Configure the CLI with your Vonage API credentials:
+     $ vcr configure
+
+  2. Initialize a new project from a template:
+     $ vcr init my-project
+
+  3. Deploy your application:
+     $ vcr deploy
+
+CORE WORKFLOW
+  • vcr configure  - Set up your Vonage API credentials and region
+  • vcr app        - Create and manage Vonage applications
+  • vcr init       - Initialize a project from a template
+  • vcr deploy     - Deploy your application to VCR
+  • vcr debug      - Run your application locally in debug mode
+  • vcr logs       - Tail or search logs from a deployed instance
+  • vcr instance   - Manage deployed instances (logs, removal)
+  • vcr secret     - Manage secrets for your applications
+  • vcr upgrade    - Update the VCR CLI to the latest version
+
 
 ### Examples
 
 ```
-$ vcr app create -n my-app
+# Configure the CLI with your Vonage credentials
+$ vcr configure
+
+# Create a new Vonage application
+$ vcr app create --name my-app
+
+# List all your Vonage applications
 $ vcr app list
+
+# Initialize a new project in the current directory
 $ vcr init
 
+# Initialize a new project in a specific directory
+$ vcr init my-project
+
+# Deploy your application to VCR
+$ vcr deploy
+
+# Run your application locally in debug mode
+$ vcr debug
+
+# View logs for a deployed instance
+$ vcr logs --project-name my-project --instance-name dev
+
+# Follow logs live (also available as: vcr instance log)
+$ vcr logs -p my-project -n dev --follow
+
+# Create a secret for your application
+$ vcr secret create --name MY_API_KEY --value "secret-value"
+
 ```
 
 ### Options
@@ -33,14 +84,14 @@ $ vcr init
 
 ### SEE ALSO
 
-* [vcr app](vcr_app.md)	 - Use app commands to manage Vonage applications
-* [vcr configure](vcr_configure.md)	 - Configure VCR CLI
-* [vcr debug](vcr_debug.md)	 - Run the application code locally in debug mode.
-* [vcr deploy](vcr_deploy.md)	 - Deploy a VCR application
-* [vcr init](vcr_init.md)	 - Initialise a new code template
-* [vcr instance](vcr_instance.md)	 - Used for instance management
-* [vcr mongo](vcr_mongo.md)	 - Used for managing MongoDB databases
-* [vcr secret](vcr_secret.md)	 - Manage VCR secrets
-* [vcr upgrade](vcr_upgrade.md)	 - Show and update VCR CLI version
-
-###### Auto generated by spf13/cobra on 26-Nov-2024
+* [vcr app](vcr_app.md)	 - Manage Vonage applications for VCR deployments
+* [vcr configure](vcr_configure.md)	 - Configure VCR CLI with your Vonage API credentials
+* [vcr debug](vcr_debug.md)	 - Run your application locally in debug mode with live VCR integration
+* [vcr deploy](vcr_deploy.md)	 - Deploy your application to Vonage Cloud Runtime
+* [vcr init](vcr_init.md)	 - Initialize a new VCR project from a template
+* [vcr instance](vcr_instance.md)	 - Manage deployed VCR instances
+* [vcr logs](vcr_logs.md)	 - Fetch logs from a deployed VCR instance
+* [vcr secret](vcr_secret.md)	 - Manage secrets for VCR applications
+* [vcr upgrade](vcr_upgrade.md)	 - Check for and install VCR CLI updates
+
+###### Auto generated by spf13/cobra on 2-Aug-2026

docs/vcr_instance_log.md

@@ -1,52 +1,84 @@
 ## vcr instance log
 
+Fetch logs from a deployed VCR instance
+
+### Synopsis
+
 Fetch logs from a deployed VCR instance.
 
-By default, the command retrieves the last N log entries (controlled by `--history`) and exits.
-Use the `--follow` (`-f`) flag to continuously stream new log entries until you press Ctrl+C.
+By default the command prints recent log entries and exits. Use --follow (-f)
+to keep streaming new entries until you press Ctrl+C.
+
+IDENTIFYING THE INSTANCE
+  • --id: the instance UUID
+  • --project-name + --instance-name: the combination from your manifest
+
+SELECTING A TIME RANGE
+  • --since 15m|2h        start from a relative point in the past
+  • --from/--to RFC3339   an explicit window
+  • --history N           limit the initial backfill (default 300)
+  --since and --from are mutually exclusive. --history composes with a
+  window: the last N entries within it.
+
+FILTERING
+  • --log-level  minimum severity: trace, debug, info, warn, error, fatal
+  • --source-type application | provider
+  • --grep       show only messages matching a Go RE2 regex
+  • --exclude    hide messages matching a Go RE2 regex
+  Use (?i) inside a pattern for case-insensitive matching.
+
+OUTPUT
+  Each line is: HH:MM:SS.mmm  level  message, preceded by a
+  "==> YYYY-MM-DD" marker whenever the calendar date changes.
+  --json prints one JSON object per line for scripting, always with
+  UTC timestamps so output does not vary by host timezone.
+
 
 ```
-vcr instance log --project-name <project-name> --instance-name <instance-name> [flags]
+vcr instance log [flags]
 ```
 
 ### Examples
 
 ```
-# Print the last logs by instance id (default, no follow):
-$ vcr instance log --id <instance-id>
-
-# Print the last logs by project and instance name:
-$ vcr instance log --project-name <project-name> --instance-name <instance-name>
-
-# Continuously stream new logs (follow mode):
-$ vcr instance log --project-name <project-name> --instance-name <instance-name> --follow
+# Print recent logs and exit
+$ vcr instance log --project-name my-app --instance-name dev
 
-# Follow logs using the short flag:
-$ vcr instance log -p <project-name> -n <instance-name> -f
+# Follow new logs (Ctrl+C to stop)
+$ vcr instance log -p my-app -n dev --follow
 
-# Print the last 500 log entries and exit:
-$ vcr instance log --id <instance-id> --history 500
+# The last 15 minutes, errors only
+$ vcr instance log -p my-app -n dev --since 15m --log-level error
 
-# Filter to show only errors and above:
-$ vcr instance log -p <project-name> -n <instance-name> --log-level error
+# An explicit window
+$ vcr instance log -i 12345678-1234-1234-1234-123456789abc --from 2026-08-02T10:00:00Z --to 2026-08-02T11:00:00Z
 
-# Show only application logs (exclude provider logs):
-$ vcr instance log -p <project-name> -n <instance-name> --source-type application
+# Only payment failures, excluding health checks, as JSON
+$ vcr instance log -p my-app -n dev --grep 'pay.*502' --exclude '/health' --json
 
-# Combine filters with follow:
-$ vcr instance log -p <project-name> -n <instance-name> -l warn -s application -f
 ```
 
 ### Options
 
 ```
+      --buffer int             Maximum log entries retained in memory (default 5000)
+  -v, --exclude string         Hide messages matching this RE2 regex
   -f, --follow                 Continuously stream new log entries (press Ctrl+C to stop)
+      --from string            Window start (RFC3339)
+  -g, --grep string            Show only messages matching this RE2 regex
       --history int            Number of historical log entries to fetch initially (default 300)
   -i, --id string              Instance UUID (alternative to project-name + instance-name)
   -n, --instance-name string   Instance name (requires --project-name)
+      --json                   Print one JSON object per line
   -l, --log-level string       Minimum log level: trace, debug, info, warn, error, fatal
   -p, --project-name string    Project name (requires --instance-name)
+      --replica string         Comma-separated replica ids or hostnames (requires a replica-capable source)
+      --reverse                Reverse the default ordering for the current mode
+      --since duration         Start from this long ago (e.g. 15m, 2h)
+      --source string          Log source: auto, graphql (default "auto")
   -s, --source-type string     Filter by source: application, provider
+      --to string              Window end (RFC3339)
+      --utc                    Print timestamps in UTC
 ```
 
 ### Options inherited from parent commands
@@ -63,6 +95,6 @@ $ vcr instance log -p <project-name> -n <instance-name> -l warn -s application -
 
 ### SEE ALSO
 
-* [vcr instance](vcr_instance.md)	 - Used for instance management
+* [vcr instance](vcr_instance.md)	 - Manage deployed VCR instances
 
-###### Auto generated by spf13/cobra on 13-Apr-2026
+###### Auto generated by spf13/cobra on 2-Aug-2026

docs/vcr_logs.md

@@ -0,0 +1,100 @@
+## vcr logs
+
+Fetch logs from a deployed VCR instance
+
+### Synopsis
+
+Fetch logs from a deployed VCR instance.
+
+By default the command prints recent log entries and exits. Use --follow (-f)
+to keep streaming new entries until you press Ctrl+C.
+
+IDENTIFYING THE INSTANCE
+  • --id: the instance UUID
+  • --project-name + --instance-name: the combination from your manifest
+
+SELECTING A TIME RANGE
+  • --since 15m|2h        start from a relative point in the past
+  • --from/--to RFC3339   an explicit window
+  • --history N           limit the initial backfill (default 300)
+  --since and --from are mutually exclusive. --history composes with a
+  window: the last N entries within it.
+
+FILTERING
+  • --log-level  minimum severity: trace, debug, info, warn, error, fatal
+  • --source-type application | provider
+  • --grep       show only messages matching a Go RE2 regex
+  • --exclude    hide messages matching a Go RE2 regex
+  Use (?i) inside a pattern for case-insensitive matching.
+
+OUTPUT
+  Each line is: HH:MM:SS.mmm  level  message, preceded by a
+  "==> YYYY-MM-DD" marker whenever the calendar date changes.
+  --json prints one JSON object per line for scripting, always with
+  UTC timestamps so output does not vary by host timezone.
+
+
+```
+vcr logs [flags]
+```
+
+### Examples
+
+```
+# Print recent logs and exit
+$ vcr logs --project-name my-app --instance-name dev
+
+# Follow new logs (Ctrl+C to stop)
+$ vcr logs -p my-app -n dev --follow
+
+# The last 15 minutes, errors only
+$ vcr logs -p my-app -n dev --since 15m --log-level error
+
+# An explicit window
+$ vcr logs -i 12345678-1234-1234-1234-123456789abc --from 2026-08-02T10:00:00Z --to 2026-08-02T11:00:00Z
+
+# Only payment failures, excluding health checks, as JSON
+$ vcr logs -p my-app -n dev --grep 'pay.*502' --exclude '/health' --json
+
+```
+
+### Options
+
+```
+      --buffer int             Maximum log entries retained in memory (default 5000)
+  -v, --exclude string         Hide messages matching this RE2 regex
+  -f, --follow                 Continuously stream new log entries (press Ctrl+C to stop)
+      --from string            Window start (RFC3339)
+  -g, --grep string            Show only messages matching this RE2 regex
+      --history int            Number of historical log entries to fetch initially (default 300)
+  -i, --id string              Instance UUID (alternative to project-name + instance-name)
+  -n, --instance-name string   Instance name (requires --project-name)
+      --json                   Print one JSON object per line
+  -l, --log-level string       Minimum log level: trace, debug, info, warn, error, fatal
+  -p, --project-name string    Project name (requires --instance-name)
+      --replica string         Comma-separated replica ids or hostnames (requires a replica-capable source)
+      --reverse                Reverse the default ordering for the current mode
+      --since duration         Start from this long ago (e.g. 15m, 2h)
+      --source string          Log source: auto, graphql (default "auto")
+  -s, --source-type string     Filter by source: application, provider
+      --to string              Window end (RFC3339)
+      --utc                    Print timestamps in UTC
+```
+
+### Options inherited from parent commands
+
+```
+      --api-key string            Vonage API key
+      --api-secret string         Vonage API secret
+      --config-file string        Path to config file (default is $HOME/.vcr-cli) (default "~/.vcr-cli")
+      --graphql-endpoint string   Graphql endpoint used to fetch metadata
+      --help                      Show help for command
+      --region string             Vonage platform region
+  -t, --timeout duration          Timeout for requests to Vonage platform (default 10m0s)
+```
+
+### SEE ALSO
+
+* [vcr](vcr.md)	 - Streamline your Vonage Cloud Runtime development and management tasks with VCR
+
+###### Auto generated by spf13/cobra on 2-Aug-2026

pkg/logs/buffer.go

@@ -0,0 +1,60 @@
+package logs
+
+import "sync"
+
+// DefaultBufferSize is the number of entries retained in memory when the user
+// does not override --buffer.
+const DefaultBufferSize = 5000
+
+// Buffer retains at most a fixed number of entries in a bounded slice. Once
+// full, adding an entry drops the oldest by shifting the remaining entries down
+// one position, so Add is O(n) in the capacity once the buffer is saturated.
+// It is safe for concurrent use: a source goroutine appends while the render
+// loop snapshots.
+type Buffer struct {
+	mu       sync.Mutex
+	entries  []Entry
+	capacity int
+}
+
+// NewBuffer returns a buffer holding at most capacity entries. A non-positive
+// capacity falls back to DefaultBufferSize.
+func NewBuffer(capacity int) *Buffer {
+	if capacity <= 0 {
+		capacity = DefaultBufferSize
+	}
+	return &Buffer{entries: make([]Entry, 0, capacity), capacity: capacity}
+}
+
+// Add appends an entry, evicting the oldest when full.
+func (b *Buffer) Add(e Entry) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	if len(b.entries) == b.capacity {
+		copy(b.entries, b.entries[1:])
+		b.entries[len(b.entries)-1] = e
+		return
+	}
+	b.entries = append(b.entries, e)
+}
+
+// Snapshot returns a copy of the retained entries, oldest-first.
+func (b *Buffer) Snapshot() []Entry {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	out := make([]Entry, len(b.entries))
+	copy(out, b.entries)
+	return out
+}
+
+// Len returns the number of retained entries.
+func (b *Buffer) Len() int {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return len(b.entries)
+}
+
+// Cap returns the configured capacity. It is deliberately lock-free because
+// capacity is immutable after construction; if the buffer ever gains a resize
+// operation, this must start taking b.mu like Len does.
+func (b *Buffer) Cap() int { return b.capacity }