CLI Quickstart and Configuration

Last validated: 2026-05-14

This guide is plugin-first and uses Scriptum through Dodil CLI:


dodil scriptum --help

1) Prerequisites

Dodil CLI binary available as dodil
Scriptum API endpoint reachable
Token and organization context for remote environments

Default endpoints used in this guide:

gRPC: rpc.dev.dodil.io:443
HTTP: https://api.dev.dodil.io:443

2) Fastest Start


# 1) Login once at Dodil CLI level
dodil login <service_account_id> <service_account_secret>
 
# 2) Optional: initialize and pin Scriptum defaults
dodil scriptum config init
dodil scriptum config set api_endpoint rpc.dev.dodil.io:443
dodil scriptum config set org_id "$SCRIPTUM_ORG_ID"
 
# 3) Verify connectivity
dodil scriptum health
dodil scriptum doctor

After dodil login, use short plugin commands without repeating --api-endpoint, --token, or --org on every command.

Optional shorthand helper:


alias scriptum='dodil scriptum'
scriptum health

3) Global Flags (All Commands)

Flag	Meaning	Example	When to use
`--config`	Explicit config file path	`--config /tmp/scriptum.yaml`	CI or multi-profile environments
`-o`, `--output`	Output format: `table`, `json`, `yaml`, `wide`	`-o json`	Automation-friendly parsing
`--api-endpoint`	API endpoint (`host:port`)	`--api-endpoint rpc.dev.dodil.io:443`	Target non-default environments
`--token`	Auth token override	`--token "$DODIL_TOKEN"`	One-off command without login
`--org`	Organization ID override	`--org org_abc`	Tenant-scoped operations
`--org-name`	Organization name override	`--org-name finance`	Human-readable tenant labeling
`--debug`	Enable debug output	`--debug`	Troubleshooting transport/auth issues
`--timeout`	Request timeout (duration)	`--timeout 45s`	Slow network/backends

4) Config Resolution and Precedence

Config path selection (first existing wins):

$SCRIPTUM_CONFIG_DIR/config.yaml
$DODIL_CONFIG_DIR/config.yaml
$DODIL_CONFIG_DIR/scriptum/config.yaml (legacy fallback)
~/.config/dodil/config.yaml
~/.scriptum/config.yaml (legacy fallback)

When writing config:

Unified-style files prefer a scriptum: section.
Flat legacy keys are still supported.

Effective setting precedence:

CLI flag
Environment variable
scriptum.* config section
global.* config section
Built-in defaults

5) Environment Variables

Supported env overrides:

DODIL_TOKEN or SCRIPTUM_TOKEN
SCRIPTUM_API_ENDPOINT
SCRIPTUM_ORG_ID
SCRIPTUM_ORG_NAME

Example:


export SCRIPTUM_API_ENDPOINT="rpc.dev.dodil.io:443"
export DODIL_TOKEN="<token>"
export SCRIPTUM_ORG_ID="org_local"
 
dodil scriptum script list -o json

6) Transport Behavior

Scriptum CLI transport behavior:

Endpoint ending with :443 uses TLS.
Other endpoints use plaintext/insecure transport.
Metadata headers are added to unary and stream calls:
- authorization: Bearer <token>
- x-organization-id
- x-organization-name

7) Common Configuration Tasks


# Inspect current config
dodil scriptum config view
 
# Set values
dodil scriptum config set api_endpoint rpc.dev.dodil.io:443
dodil scriptum config set org_id "$SCRIPTUM_ORG_ID"
dodil scriptum config set output json

8) Recommended Setup Profiles

Dev cloud default

rpc.dev.dodil.io:443
Login once via dodil login
Run short form dodil scriptum ... commands
Use doctor before test runs

Explicit override mode

Use --api-endpoint rpc.dev.dodil.io:443 only when overriding config for one command.
Use --token and --org only for temporary manual overrides.

CI pipelines

Prefer env vars + explicit flags
Avoid writing long-lived tokens to disk
Use -o json and parse responses deterministically