AI Characters & Agents

The CLI reference for 5AM's AI characters: create and chat with them, wire up webhooks, manage server and local skills, deploy Server Agents on your own machines, and orchestrate multi-character Playground sessions.

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).

A character's token never reads the keys saved in your account. Where the CLI runs with a character's token, set GEMINI_API_KEY (and, from CLI v1.8.97, OPENAI_API_KEY) in that environment: a key used there and nowhere else. 5am keys set is not the way: it replaces the key saved in your account, for everything you run. AI credits need no key when the character's token has write scope. From CLI v1.8.97 the CLI says when a key is hidden from a character's token (cli_token_not_person), and 5am keys list prints keys_hidden_reason.

sh
# List all stored API keys
5am keys list

# Set provider keys
5am keys set gemini <key>    # → {"provider":"gemini","status":"updated","stored_locally":true}
5am keys set openai <key>

# Delete stored keys
5am keys delete gemini --yes # → {"provider":"gemini","status":"deleted"}

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.

sh
# Management
5am characters list
5am characters get <characterId>
5am characters create --name "Pico" --skills get_album_images,fetch_media
5am characters create --name "Scout" --ai-model gemini-4-hydrogen
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

Creating a character, update, and adding, changing or removing its webhooks (webhooks listen too) take your own login or your own token. An AI character's token (even its own) and a workflow run's token get 403 cli_token_not_allowed_here, so a character can never widen its own scopes or rewrite itself. With your own token, --scopes can't go above that token's scopes: asking for admin from a read-and-write token is refused with insufficient_scope and nothing is created. These are server rules, so they apply with every CLI version.

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.
  • --ai-model: The text model the character thinks with (also on update). gemini-3-flash-preview is the default; gemini-3.8-flash, gemini-4-hydrogen (the newest Flash model), gemini-3.1-pro-preview, and gpt-5.6-luna or gpt-5.6-sol (these use your own OpenAI key, for chat and skills only) are the other choices. The server checks the value, so every CLI version takes it.

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.

sh
# 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.

Notices From Your Agent

From CLI v1.8.98, your own agent (a coding agent, a script, a scheduled job) can post an answer into one of your character chats: a card titled --title, the markdown of --text-file, and, with --html-file, an HTML report shown under the text in the chat's sandboxed preview. The card says From your agent, or From and your --source label. It shows on the web, iOS and Android, arrives live and counts as unread. It is never the character's own words: the character does not see it in its chat history or memory.

sh
# A card with a markdown answer
5am characters notice <characterId> --title "Nightly check" --text-file ./answer.md

# With an HTML report, a label, and a key so a retry never posts twice
5am characters notice <characterId> --title "Weekly growth report" --text-file ./summary.md \
  --html-file ./report.html --source crew --key growth-2026-W46 --json

# The text from stdin
echo "All green." | 5am characters notice <characterId> --title "Deploy done" --text-file -

Command Arguments:

  • --title: The card's title, 1 to 120 characters (required).
  • --text-file: A markdown file with the card's text, at most 8000 characters (required; - reads stdin).
  • --html-file: An HTML report, at most 262144 bytes. The CLI refuses a larger file before sending. It runs in the same sandbox as a character's interactive previews: scripts load only from a few public CDNs such as cdnjs, jsDelivr and unpkg, images only from the report itself (data: URLs), and the page has no access to your account. Images in the text show as links you can open, and code blocks in the text (HTML included) show as code: only --html-file runs.
  • --source: A label for the card, at most 40 characters, for example crew.
  • --key: An idempotency key, at most 200 characters. Posting again with the same key to the same character answers the notice already posted ("replayed": true) and writes nothing.
  • --json: Prints {"interaction_id": "...", "replayed": false} instead of a line of text.

Posting takes your own login or your own token with write scope. An AI character's token, a workflow run's token and a read-only token get 403 cli_token_not_allowed_here. The character must be yours. At most 60 notices an hour per account; past that the CLI prints how many minutes to wait. Posting does not need a paid plan.

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?

  1. 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).
  2. 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.
  3. 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. Only your own login, or a token of yours with write scope, sees a webhook's secrets: with a read-only token, an AI character's token or a workflow run's token, webhooks list shows access_token and the outbound auth's token or header_value as null, the URL as its origin only (url_hidden) and the last delivery error only as a code such as invalid_header or timeout, and a webhook test with a character's or a run's token leaves out the receiver's reply. Changing a webhook's URL or outbound auth clears its last delivery error. These are server rules, so they apply with every CLI version. Webhooks can only be managed by users logged in via 5am login or using a Personal Access Token with the admin scope.

sh
# 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:

  1. 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
  2. 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.

sh
# 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 --input '{"album_id": "..."}'
5am characters skills execute <characterId> get_album_images --input-file input.json   # '-' reads stdin

Command Arguments for execute:

  • <toolName>: a skill enabled on that character (skills tools <characterId> lists them, with their input fields). Any other skill fails with Skill "<name>" is not enabled for this character.
  • --input: the tool input as a JSON object, with the field names from skills tools.
  • --input-file: the same JSON from a file (- reads stdin). Use one or the other.
  • --quiet-push: stage_outreach only. The new draft sends you no review notification (for recording an email that already went out). It is a flag beside the input, never a key in it, and only your own login or token honors it, not a character's token.

execute needs a token with the write scope (a character's auto-minted token is read unless you pass --scopes) and a Premium plan or above, like the rest of AI Characters. A scope denial (insufficient_scope) or an input problem (success: false with an error) comes back in the JSON body with exit code 0, so check the output rather than the exit code.

Example: Working a Pipeline by Hand

The pipeline skills (pipeline_query, pipeline_upsert, stage_outreach) are the ones a sales character such as the Sales Director uses in chat; with them enabled you can run the same steps yourself. This records an email you already sent, so the pipeline knows the prospect was contacted:

sh
# 1. Find the item by name (case-insensitive). The answer carries item.item_id and
#    contacts[].contact_id; an unknown name answers mode "item_not_found" with the closest matches.
5am characters skills execute <characterId> pipeline_query --input '{"mode":"get_item","name":"Acme Podcast"}'

# 2. Only if it does not exist: create it with its contact. The name is the key, so the
#    same name updates that item, and contacts merge by email.
5am characters skills execute <characterId> pipeline_upsert --input '{"entity":"item","name":"Acme Podcast","website":"https://acme.example","contacts":[{"name":"Sam Lee","email":"sam@acme.example","is_primary":true}]}'

# 3. The email exactly as you sent it, to the address it went to (or pass "contact_id"
#    instead of the two recipient fields).
5am characters skills execute <characterId> stage_outreach --quiet-push \
  --input '{"item_id":"<itemId>","recipient_name":"Sam Lee","recipient_email":"sam@acme.example","subject":"<as sent>","body":"<as sent>"}'

stage_outreach never sends anything: it stages a draft for review. To mark this one as sent, approve it and record when it left (5am pipeline outreach approve <draftId>, then mark-sent <draftId> --sent-at <time>), as Recording an Email You Already Sent explains.

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 FIVEAM_SKILLS_DIR environment variable, from CLI v1.8.8; earlier releases read only 5AM_SKILLS_DIR, which a program can set but a shell cannot). 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:

sh
# 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.

sh
# 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:

sh
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:

sh
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.

sh
# 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

Command Arguments:

  • <orchestratorId>: The ID of the character acting as the orchestrator (obtainable by running 5am playground orchestrators).
  • <sessionId>: The unique ID of the active playground session, returned when you create a session.

Approving a proposal creates a character, so it takes your own login or your own token, like create. An AI character's token and a workflow run's token get 403 cli_token_not_allowed_here, and the proposal waits for you. From CLI v1.8.94, playground task --auto-approve-proposals stops at that refusal with exit code 2 and says the proposal is waiting for you; older versions kept polling until the task timed out.

FAQ

What is the difference between 5am skills and 5am characters skills?
These manage two entirely different types of skills:

  • 5am skills (Global Local Skills): Manages custom local tools installed on your specific machine (the JSON manifests in ~/.5am/skills/). Enabling or disabling a skill here toggles whether that tool is available locally for any character you chat with on your machine.
  • 5am characters skills (Server-Side Skills): Interacts with the cloud platform to manage skills that run on 5AM's servers (like get_album_images). To enable or disable cloud skills for a specific character, you update the character itself using 5am characters update <id> --skills "skill1,skill2".