AI API Keys

Manage your third-party API keys (Gemini, OpenAI) used for AI Media Generation. Keys are stored securely in your native system keychain (macOS Keychain, Linux Secret Service, or Windows Credential Manager).

# List all stored API keys
5am keys list

# Set provider keys
5am keys set gemini <key>
5am keys set openai <key>

# Delete stored keys
5am keys delete gemini --yes

AI Characters

Create and chat with autonomous AI characters that have access to your local files and skills. Note: interacting with AI characters requires a paid 5AM subscription.

# Management
5am characters list
5am characters get <characterId>
5am characters create --name "Pico" --skills get_album_images,fetch_media
5am characters update <characterId> --name "Pico v2"
5am characters delete <characterId> --yes

# Chat interactively
5am characters chat <characterId>

# Run a single prompt with autonomous tool execution
5am characters chat <characterId> "create a summary.txt of my recent work" --auto-approve

Command Arguments for create:

--name: The name of the character.
--skills: Comma-separated list of local skills to enable.
--from-file: Path to a JSON file containing the full character profile.
--scopes: Scopes for the auto-minted CLI token (default: read).
--system-instruction: The system prompt to guide the character's behavior.
--system-instruction-file: Path to a .md or .txt file containing the system prompt.
--no-token: Create the character without automatically minting an access token.

Command Arguments for chat:

[message]: The prompt to send. If omitted, the CLI opens an interactive chat session.
--auto-approve: Bypass the confirmation prompt for local tool execution.
--history: Path to a JSON file to load and save chat history across multiple runs.
--no-save: Prevents writing the conversation back to the --history file.
--allow-outside-workspace: Permits the AI to read/write files outside your current directory.
--download-media: Automatically downloads any media the AI generates to your local disk.
--download-dir: Directory to save downloaded media.
--render-html-open: Automatically opens generated HTML interfaces in your default browser.
--json: Outputs the raw JSON response instead of human-readable text.

Scheduled Tasks

A scheduled task makes a character act on its own: you save a prompt once, and the character runs it once a day (02:30 UTC) through the exact same chat pipeline as an interactive message — same skills, memory, and webhooks. Each run lands in the chat thread and you're notified (push-first, email fallback); when a task reaches its end date, you get a one-time recap email summarizing every run. Think "post a morning haiku about my photo library" or "summarize yesterday's uploads" — set it and forget it.

# Create: run the prompt daily until cancelled (paid plan required)
5am characters tasks create <characterId> --prompt "Post a morning haiku about my photo library"

# Bounded window, posting each run's result into a Playground session
5am characters tasks create <characterId> --prompt "Summarize yesterday's uploads" \
  --start-date 2026-09-01 --end-date 2026-09-30 --session <sessionId> --budget-tokens 20000

# List a character's tasks (newest first)
5am characters tasks list <characterId>

# Update — only the flags you pass change; --clear-* removes a value
5am characters tasks update <characterId> <taskId> --prompt "…" --end-date 2026-10-15
5am characters tasks update <characterId> <taskId> --clear-end-date    # run until cancelled
5am characters tasks update <characterId> <taskId> --status active     # resume a cancelled task

# Cancel — the task stops, but its row and run history are kept
5am characters tasks cancel <characterId> <taskId>

Command Arguments:

--prompt: The message the character runs daily (required on create).
--start-date / --end-date: UTC calendar days (YYYY-MM-DD) — the first day the task may run and the last day inclusive. Omit both to start immediately and run until cancelled.
--session: A Playground session ID — each run's result is posted into the session, and the team reacts to it.
--budget-tokens: A soft per-run token ceiling for that Playground reaction round.
On update, the date/session/budget flags are three-state: pass the flag to set a new value, its --clear-* twin (--clear-end-date, --clear-start-date, --clear-session, --clear-budget-tokens) to remove it, or neither to leave it unchanged.

Note:

Creating and updating tasks requires a paid plan (the daily runs use the paid chat pipeline). Cancelling works on any plan — stopping a task is an owner-control action — but needs a token with the admin scope, like the other owner controls. Scheduled tasks can also be managed from the character's edit page on the web and in character settings on iOS.

Character Webhooks

What is a webhook? A webhook is an automated HTTP push notification. Instead of your application constantly polling our API to ask "Is the chat done yet?" or "Did the character use a skill?", our server will instantly send an HTTP POST request to a URL you provide as soon as the event happens.

How does it work?

Create: You register a webhook URL (e.g., https://api.yourdomain.com/webhook) and specify which events you care about (e.g., chat.completed, skill.executed).
Trigger: When your AI character finishes generating a response or runs a server-side skill, our backend bundles the data into a JSON payload and sends it to your URL.
Verify: To ensure the request actually came from us and wasn't spoofed, we sign every delivery. When you create a webhook, the CLI will output an access_token — this is your signing secret! Every webhook request includes an X-5am-Timestamp header and an X-5am-Signature header (formatted as sha256=<hex>). To verify it, you compute an HMAC-SHA256 hash using your secret against the string <timestamp>.<body>. If your hash matches the one in X-5am-Signature, the event is authentic.

Important:

A leaked webhook secret could allow attackers to send fake events to your server. Use the rotate-secret command if you suspect a secret has been compromised. Webhooks can only be managed by users logged in via 5am login or using a Personal Access Token with the admin scope.

# List all webhooks for a character
5am characters webhooks list <characterId>

# Create a new webhook
5am characters webhooks create <characterId> --name "My Webhook" --url "https://api.example.com/webhook" --events "chat.completed,skill.executed"

# Update an existing webhook
5am characters webhooks update <characterId> <webhookId> --url "https://api.example.com/new-url"

# Send a test payload to verify connectivity and signature
5am characters webhooks test <characterId> <webhookId>

# Rotate the HMAC signing secret for a webhook
5am characters webhooks rotate-secret <characterId> <webhookId>

# Delete a webhook
5am characters webhooks delete <characterId> <webhookId> --yes

Tip:

Local Testing If you don't want to write your own server just yet and only want to inspect payloads, use the CLI's built-in listener! It spins up a temporary server, automatically registers the webhook, verifies the HMAC signatures for you, and pretty-prints the incoming events to your terminal:

5am characters webhooks listen <characterId> --url http://localhost:8080 --port 8080 --path /webhook

How to trigger test payloads to your listener:

Keep your webhooks listen command running in Terminal A. Look closely at its output when it starts up; it prints the ID of the temporary webhook it created: [5am] webhook <TEMPORARY_ID> registered at http://localhost:8080/webhook
In Terminal B, run the test command using that <TEMPORARY_ID>: 5am characters webhooks test <characterId> <TEMPORARY_ID>

Character Server Skills

Manage and execute cloud-based server skills (like get_album_images) for a character.

# List all skills the platform exposes (not character-specific)
5am characters skills available

# Show Gemini tool definitions for a character's enabled skills
5am characters skills tools <characterId>

# Manually execute a server skill as the character (useful for testing/debugging)
5am characters skills execute <characterId> get_album_images --args '{"albumId": "..."}'

AI Character Local Skills

Manage custom local tools that your AI characters can execute. Custom skills are defined as JSON manifests stored locally in ~/.5am/skills/ (or via the $5AM_SKILLS_DIR environment variable). The CLI dynamically forwards these definitions to the AI model so it can invoke them as native tools during a ai character chat session.

Manifest Schema: A custom skill requires a name (snake_case, avoiding clashes with built-ins), a description, an OpenAPI-style input_schema (defining the arguments the AI should provide), and either a run array (safer, argv execution) or a shell string (for piping and redirection).

Example 1: Safe Arguments Execution (run) In run mode, arguments are passed exactly as specified without shell parsing, preventing quoting hazards. The AI's inputs are injected via {{key}} syntax.

json

{
  "name": "git_status",
  "description": "Run git status in a specified local repository",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "Absolute path to the repository" }
    },
    "required": ["path"]
  },
  "run": ["git", "-C", "{{path}}", "status", "--short"],
  "timeout_seconds": 30
}

Example 2: Shell Execution (shell) In shell mode, inputs from the AI are mapped to environment variables before execution. Use this only when you explicitly need shell pipelines, subshells, or redirects.

json

{
  "name": "find_large_files",
  "description": "Find the largest files in a directory",
  "input_schema": {
    "type": "object",
    "properties": {
      "dir": { "type": "string", "description": "Directory to scan" },
      "count": { "type": "integer", "description": "Number of files to return" }
    },
    "required": ["dir", "count"]
  },
  "shell": "find \"$dir\" -type f -exec ls -lh {} + | sort -k 5 -hr | head -n \"$count\"",
  "max_output_bytes": 131072
}

Management Commands:

# List all available skills (built-in and custom)
5am skills list

# Include disabled skills in the list
5am skills list --all

# Validate a custom skill's JSON manifest before installation
5am skills validate ~/.5am/skills/my_skill.json

# Enable or disable a custom skill
5am skills enable <skillName>
5am skills disable <skillName>

Server Agents & Datasets

Deploy the CLI on your own servers as a lightweight agent and your AI characters can answer live questions about them in chat — "how many unique IPs connected in the last 24 hours?", "what was peak CPU overnight?". Your data stays in a local SQLite store on the server; only query results (a count, a top-ten list, an average) ever transit 5AM. The agent only dials out over HTTPS — no inbound port, no TLS certificate to manage, works behind NAT and firewalls.

Ingest data into typed datasets. Describe your data once with a schema file (string, number, timestamp fields, plus an optional time_field for time-range queries), then feed it lines. nginx/apache access logs are parsed natively; everything else is JSONL — one JSON object per line.

# Schema: { "fields": { "ip": "string", "path": "string", "status": "number",
#           "ts": "timestamp" }, "time_field": "ts" }

# Ingest an access log. --file keeps a resume checkpoint, so re-running only
# ingests NEW lines (safe to cron); log rotation is detected automatically.
5am data ingest --dataset requests --schema requests.schema.json \
    --file /var/log/nginx/access.log --format combined

# Add --follow to tail continuously (run under systemd)
5am data ingest --dataset requests --schema requests.schema.json \
    --file /var/log/nginx/access.log --format combined --follow

# Anything that prints JSON lines is a dataset — app logs, metrics scripts,
# journald:
journalctl -o json -u my-app | 5am data ingest --dataset app_journal --schema journal.schema.json

Query locally with the same engine your characters use — handy for checking what they'll see:

5am data query --dataset requests --op count_distinct --field ip --since -24h
5am data query --dataset requests --op group_by --field path --limit 5
5am data query --dataset sysmetrics --op stats --field cpu_pct --since -24h   # min / max / avg
5am data query --dataset sysmetrics --op latest                                # most recent sample
5am data query --dataset requests --op count --filter 'status:gte:500' --since -7d
5am data list                                                                  # datasets + row counts
5am data prune --dataset requests --keep-days 30                               # retention

Run the agent and connect a character:

5am serve agent --name web-1     # the daemon: registers + answers queries (systemd in production)
5am agent list                   # your fleet, with online status
5am agent remove web-1           # revoke an agent

Enable the Query Server Agent skill on a character (Skills tab, or --skills query_server at create) and ask away — answers arrive inline in the chat turn, typically in 1–3 seconds. You can register any number of named agents (web-1, db-1, …); the character sees the whole fleet and routes questions to the right machine.

Security model, in short: the agent runs on a read-only token (agent endpoints deliberately require only read scope), characters can execute only built-in dataset queries and the custom skills you declared in ~/.5am/skills/ (never arbitrary commands — and destructive-flagged skills are refused unless the daemon runs with --allow-destructive), queries are a structured language with validated fields and bound parameters — never raw SQL — and if an agent is offline your character says so instead of inventing numbers. The full runbook (systemd units, schema reference, metrics-sampler example) ships in the CLI repo as docs/SERVER_AGENT.md.

The AI Playground

The Playground is an advanced feature where multiple AI characters collaborate on a task. You start a session with one orchestrator character, then submit tasks in plain English. The orchestrator breaks the task into pieces and delegates them to specialist characters while results stream back live.

# List characters flagged as orchestrators
5am playground orchestrators

# List all your playground sessions
5am playground sessions list

# Get details about a specific session
5am playground sessions get <sessionId>

# Create a new playground session
5am playground sessions create <orchestratorId>

# Submit a task to an active session
5am playground task <sessionId> "Research the history of the Apollo missions and write a summary"

# View messages from a session
5am playground messages <sessionId>

# Delete a session
5am playground sessions delete <sessionId> --yes